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
- A workspace with a production version. The end-user server only answers from the version promoted to production. See Environments.
- 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. - 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 throughdeps, 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 (
5mto7d). When it has expired, the server answers401, 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
A tool says the Upsolve sign-in has expired
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.The agent says the workspace has no published version
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.
A tool is not found
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.
Answers show data the user shouldn't see
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 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.