Connect Claude Code to Semogram

Set up a Semogram workspace MCP connection, authenticate, verify evidence-backed reads, and manage access in Claude Code.

The steps below follow the client’s documented MCP setup. This client connection has not yet been verified end to end against Semogram; complete the first-read checks below to verify your workspace access.

Install

Before you start

You need a Semogram account with access to the workspace and permission to read the records you intend to inspect. Connecting an assistant does not create a workspace, import data, or grant additional permissions.

In Semogram, open the workspace Settings and copy the URL from Connect an AI assistant. Use the copied UUID-based URL, not the workspace name, the homepage, or the sign-in URL. Its shape is:

https://platform.semogram.com/api/mcp/workspaces/<WORKSPACE_ID>

Replace every placeholder below with that copied URL. The URL identifies the workspace; it does not contain an API key. This guide uses OAuth sign-in.

Add Semogram to Claude Code

Run this in your terminal, replacing the quoted URL:

claude mcp add --transport http --scope user semogram "<YOUR_WORKSPACE_MCP_URL>"

--scope user makes the connection available to your user across local projects. For a connection limited to the current directory, choose --scope local. Use --scope project when intentionally sharing the server configuration through the repository's .mcp.json; each teammate still signs in with their own Semogram account. Keep credentials out of repository files.

Check the saved configuration:

claude mcp get semogram

Confirm the URL matches the workspace you selected. If the name already exists, inspect that entry before replacing it; use a distinct server name when keeping more than one workspace connection.

Start Claude Code and run /mcp. Select semogram and follow its authentication flow. The browser opens Semogram's sign-in and consent screens. Use an account that belongs to the workspace, review the connection, and approve it. Return to Claude Code and check the server status in /mcp.

Adding a URL and completing OAuth are separate steps. If the connection reports that authentication is needed, finish sign-in before asking it to read data.

Make your first read

Start a conversation with this request:

Use the Semogram MCP connection. Discover my available capabilities, confirm the workspace name and ID, and list the projects I can access. Do not change anything.

The assistant should use discover_capabilities, workspace_get, and project_list. Check the returned workspace and choose the intended project. Project tools on a workspace connection require its projectId; workspace resources such as sources and uploads do not.

Then ask about a known record or published query:

Use Semogram to inspect the delivery query we published for this project. Explain its inputs and show the records and run references behind its result. If the query is missing, tell me rather than creating one.

Use your own query name. A successful connection does not mean that this example query exists or that an answer is correct. Compare the returned evidence with a record you recognize before expanding the task.

Manage the connection

Check status with /mcp or inspect the configuration with claude mcp get semogram. To remove this user-scoped configuration, run:

claude mcp remove --scope user semogram

Use the matching scope if you added it elsewhere. Removal disconnects this client configuration; it does not delete Semogram workspace data.

FAQ

What permissions does the assistant have?

Your current Semogram membership and permissions determine the available tools. Some mutations require confirmation or a current member approval under the operation's policy. An assistant's approval prompt and Semogram's server-side approval requirements are separate checks.

For long-running work, keep the returned job or operation ID and check its status. Saving a draft is not the same as executing it. The records returned by Semogram are sent to the assistant provider; use a client and account approved for the data your organization permits it to receive.

Why is the connection failing?

What you see	What to check
Sign-in is requested again or `401 missing_token`	Authenticate again in the client. Verify that you are signing into Semogram, not only the assistant provider.
`404 workspace_not_found`	Copy the URL again and check workspace membership for the account used during sign-in. A name or slug cannot replace the UUID.
The assistant responds without using Semogram	Name the connection explicitly, check that it is enabled, and ask it to discover the available tools.
Expected tools or projects are absent	Check your Semogram membership and permissions. Reconnecting does not grant access.
`405` when opening the MCP URL	A browser sends GET; Semogram's MCP endpoint accepts POST. Verify through the client rather than judging the browser response.
`429`	Wait for the `Retry-After` interval. See workspace consumer API limits.

For API-key scopes, source-write restrictions, and the complete error list, use the MCP reference.

Where can I learn more?

Read MCP tools and permissions, or return to assistant setup. For client controls that vary by version, consult Claude Code MCP documentation.

Connect Claude Code to Semogram

On this page