Skip to main content
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 already uses, so it sees only that user’s data. 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.
  2. Embed tokens for your users. Your backend gets them from POST /v1/api/projects/embed-token, the same way it does for the workspace embed.
  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 server over Streamable HTTP: 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 2.x. Each agent run gets that user’s embed token through deps, so one agent serves all your users:

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.
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

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 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

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.
The end-user server only answers from the production version. Save a version of the workspace and promote it.
The end-user server only has end-user tools. Tools for building and testing a workspace, such as the Playground, aren’t on it.
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 rules.

Next steps

Embed Upsolve in your product

Get embed tokens for your users.

Upsolve MCP Server

Connect Claude, Cursor and other assistants with an Upsolve account.