> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Upsolve in Your Own Agent

> Give your own AI agent or MCP server your Upsolve workspace as a sub-agent: it asks the workspace's analytics agent questions as each of your users, with the embed tokens you already use.

If you're building your own AI agent, you can give it your Upsolve workspace as a tool. Your agent passes the data questions to the workspace's analytics agent, and gets back the answer, the chart data and the SQL behind it. Each call runs as one of your users, with the same embed token your [workspace embed](https://docs.upsolve.ai/embedding.md) already uses, so it sees only that user's data.

| | Embed the workspace | Embed in your agent (this page) |
| - | - | - |
| **What users get** | Upsolve's chat, favorites and canvases in your app | Your own agent, which asks Upsolve for answers |
| **How** | An `<iframe>` | Upsolve's end-user MCP server, called from your backend |
| **Sign-in** | Your backend gets an embed token for each user | The same embed token, sent as a bearer token |
| **Whose data** | Each user's own | Each user's own |

Your agent can only reach the end-user tools: ask the workspace's agent questions and work with that user's own conversations, favorites and canvases. It can't reach any tools for building or changing a workspace.

## Before you start

1. **A workspace with a production version.** The end-user server only answers from the version promoted to production. See [Environments](https://docs.upsolve.ai/ai-agent-builder/environments.md).
2. **Embed tokens for your users.** Your backend gets them from [`POST /v1/api/projects/embed-token`](https://docs.upsolve.ai/api-reference/endpoint/create-embed-token), the same way it does for the [workspace embed](https://docs.upsolve.ai/embedding.md).
3. **Your organization, project and workspace IDs.** They're the ones your embed already uses.

## Connect

The end-user MCP server is a standard [Model Context Protocol](https://modelcontextprotocol.io) server over Streamable HTTP:

| | |
| - | - |
| **URL** | `https://mcp.upsolve.ai/user` |
| **Auth** | `Authorization: Bearer <embed token>` |

Any MCP client that can send its own `Authorization` header can connect. There's no OAuth sign-in: the embed token is the sign-in.

### Example: Pydantic AI

This uses [Pydantic AI](https://ai.pydantic.dev) 2.x. Each agent run gets that user's embed token through `deps`, so one agent serves all your users:

```python theme={null}
from dataclasses import dataclass

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPToolset

ORG_ID = "<your organization id>"
PROJECT_ID = "<your project id>"
WORKSPACE_ID = "<your workspace id>"


@dataclass
class Deps:
    upsolve_token: str  # this user's embed token, from POST /v1/api/projects/embed-token


ALLOWED = {
    "workspaces_chat_data",
    "workspaces_query",
    "workspaces_me_threads_list",
    "workspaces_me_threads_get",
}

upsolve = MCPToolset(
    "https://mcp.upsolve.ai/user",
    auth=lambda ctx: ctx.deps.upsolve_token,  # sent as "Authorization: Bearer <token>"
).filtered(lambda ctx, tool: tool.name in ALLOWED)

agent = Agent(
    "<your model>",
    deps_type=Deps,
    toolsets=[upsolve],
    instructions=(
        "For any question about the user's data, call workspaces_chat_data with "
        f"organizationId={ORG_ID}, projectId={PROJECT_ID}, workspaceId={WORKSPACE_ID} "
        'and messages=[{"role": "user", "content": "<the question>"}]. '
        "For a follow-up question, pass the thread_id the previous answer returned."
    ),
)

result = await agent.run(
    "How many orders did we get last month?",
    deps=Deps(upsolve_token=embed_token_for_this_user),
)
```

## Pass the IDs yourself

The tools that list a person's organizations, projects and workspaces (`me_list`, `me_projects_list` and `me_workspaces_list`) need a signed-in Upsolve account. With an embed token they fail with an authentication error. Leave them out, as the example does, and give your agent the organization, project and workspace IDs in its instructions.

> [!NOTE]
>
> The server's own instructions tell an assistant to start with `me_list`. Pydantic AI leaves server instructions out by default (`include_instructions=False`), so keep it that way. If your client adds server instructions to the prompt, turn that off, or your agent may stop when `me_list` fails.

## Which tools to use

| Tool | Use it for |
| - | - |
| `workspaces_chat_data` | **Any data question.** It asks the workspace's analytics agent, using all the context, skills and tests you set up, and returns its answer. Pass the returned `thread_id` on follow-ups and the agent remembers the conversation. |
| `workspaces_query` | A quick number, with no chart. Faster than a full agent turn. |
| `workspaces_me_threads_list`, `workspaces_me_threads_get` | Pick up this user's earlier conversations. |
| `workspaces_me_favorites_*`, `workspaces_me_canvases_*` | Optional: save charts and build canvases in this user's account. They show up in your [workspace embed](https://docs.upsolve.ai/embedding.md) too. |

Use `workspaces_chat_data`, not `workspaces_chat`. They run the same turn, but `workspaces_chat` is built for clients like Claude that draw charts in the conversation. `workspaces_chat_data` returns plain content your agent can read.

A `workspaces_chat_data` result has:

* **An access note** that says whether row-level security narrowed the answer.
* **The answer**, in markdown.
* **The charts**: each chart's config, its rows and the SQL that produced them.
* **The `thread_id`**, for follow-ups.

## Tokens

* **One token per user.** Each call runs as the user the token was made for, under their [data governance](https://docs.upsolve.ai/ai-agent-builder/data-governance.md) rules. Never share one user's token with another.
* **Tokens expire.** You choose how long a token lasts when you create it (`5m` to `7d`). When it has expired, the server answers `401`, and you need a new token for the next run.
* **Keep it in your backend.** Pass the token to your MCP client, as in the example, never to the model in its prompt.
* **Use embed tokens.** Use tokens from `POST /v1/api/projects/embed-token`. The server refuses legacy tenant tokens.

## Troubleshooting

> [accordion] A tool says the Upsolve sign-in has expired
>
> If it's `me_list`, `me_projects_list` or `me_workspaces_list`, that's
> expected with an embed token: leave those tools out and pass the IDs
> yourself. If it's any other tool, the token has expired. Get a new one.

> [accordion] The agent says the workspace has no published version
>
> The end-user server only answers from the production version. Save a
> version of the workspace and promote it.

> [accordion] A tool is not found
>
> The end-user server only has end-user tools. Tools for building and
> testing a workspace, such as the Playground, aren't on it.

> [accordion] Answers show data the user shouldn't see
>
> The answer is narrowed by the properties you sent when you created the token.
> Check the access note in the result, and the token's properties against
> your [data governance](https://docs.upsolve.ai/ai-agent-builder/data-governance.md) rules.

## Next steps

> [card] [Embed Upsolve in your product](https://docs.upsolve.ai/embedding.md)
>
> Get embed tokens for your users.

> [card] [Upsolve MCP Server](https://docs.upsolve.ai/ai-agent-builder/deploy-agents/mcp-server.md)
>
> Connect Claude, Cursor and other assistants with an Upsolve account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.