Semogram Docs
MCP

Connection, authentication and troubleshooting

Find your Semogram workspace MCP URL, configure an AI client, authenticate with OAuth or API keys, and inspect tool permissions and rate limits.

Every workspace has an MCP (Model Context Protocol) server. An AI assistant connected to it can answer questions with evidence, review records and runs, run and check pipelines, and propose corrections. It works with the same permissions, approvals, and audit trail as the app.

Find your MCP URL

For a connection that lets you choose a workspace during sign-in, use:

https://platform.semogram.com/api/mcp

Sign in, select a workspace, and approve access. Nothing is selected for you. Each connection keeps its own workspace choice, so connecting another workspace does not change an existing connection. This shared URL requires OAuth; use a workspace or project URL below for API keys.

Open your workspace Settings. The Connect an AI assistant panel shows the URL with a copy button. It looks like this:

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

The workspace ID is a UUID. Workspace names and slugs are not accepted.

A project-scoped server is also available at /api/mcp/projects/<PROJECT_ID>. Use it when an assistant should only see one project.

Connection details

SettingValue
TransportStreamable HTTP, POST only. SSE and stdio are not supported.
AuthenticationOAuth sign-in, or a workspace API key as a bearer token.
DiscoveryThe first request returns 401 with a WWW-Authenticate header that points to the protected-resource metadata.

Configure your client

For complete walkthroughs, choose Claude Code, Claude web or desktop, or Codex CLI. Start with assistant setup if this is your first connection.

  • Claude Code: run claude mcp add --transport http semogram <URL>, then run /mcp and choose semogram to sign in.

  • Claude (web or desktop): open the Connectors area (Customize → Connectors on web, or the equivalent in desktop), then add a custom connector with the URL.

  • Codex CLI: add the server to ~/.codex/config.toml, then run codex mcp login semogram:

    [mcp_servers.semogram]
    url = "<URL>"
  • Any other MCP client: add a remote HTTP (Streamable HTTP) server with the URL and sign in with OAuth.

For editor-specific configuration, see Cursor, Zed, VS Code, Windsurf, and JetBrains AI Assistant.

Sign-in and API keys

OAuth. The client opens a consent screen. You sign in with your own Semogram account and approve the connection. The token is bound to the MCP URL you connected to. What the assistant can do comes from your current workspace membership, not from the token. If you lose access to the workspace, the assistant loses it too.

For the shared URL, the OAuth client must support dynamic client registration, authorization code with S256 PKCE, and the resource indicator for that exact URL. The requested scope is mcp. Access tokens last one hour; refresh tokens rotate on use. After 90 days, connect again to renew authorization.

Open Connected applications from the workspace MCP panel to see your shared connections and revoke one. Revocation stops both access and refresh tokens immediately. Changing the selected workspace requires a new connection and consent. The existing workspace and project URLs retain their authentication flows.

API keys. For non-interactive use, send a workspace API key (prefix crv_) as Authorization: Bearer <key>. The key needs the projects:read scope. Create keys in Settings, then API access. Read the key from an environment variable. Never paste it into a chat.

Tools and permissions

Tool responses include data and provenance together in JSON. The evidence field identifies the sources or published releases behind a result; these references are not file attachments and do not require a file-loading approval. Your client may still ask for approval to run a tool or download an actual file.

See the MCP tools reference for discovery, resource scopes, operation approvals, and asynchronous work.

Rate limits

Requests are limited per minute. Defaults:

LimitDefaultApplies to
Organization requests600All API keys and signed-in assistants in the workspace, combined
Requests per key or assistant user120Each API key, and each person signed in over OAuth

Change both in Settings, then Consumer API limits. A request over the limit gets 429 with a Retry-After header in seconds.

Troubleshooting

SymptomCauseFix
401 missing_token or the client asks you to sign inNo token, or the token expiredSign in again from the client. In Claude Code, run /mcp.
404 workspace_not_found, or the client reports "endpoint not found"The URL has the wrong workspace ID, or the signed-in account is not a member of that workspaceCopy the URL again from the workspace. Check that you signed in with an account that belongs to the workspace.
404 org_not_found with an API keyThe key belongs to another workspaceUse a key created in this workspace.
403 insufficient_scopeThe API key lacks projects:readCreate a key with that scope.
403 workspace_resources_not_allowedThe API key is limited to projects and lacks the Workspace resources grantCreate a key in Settings, then API access, with Workspace resources turned on.
403 sparql_disabledConsumer SPARQL access is turned offAn owner or admin turns it on in Settings.
403 api_key_requiredA source_write_* tool was called over OAuthConnect with an API key that has the data:write scope and a write grant on the endpoint.
405 on GETThe client tried to open a standalone SSE streamExpected. Check whether the client completes initialization over POST.
429 rate_limit_exceededOver the per-minute limitWait for Retry-After, or raise the limits in Settings.