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
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
| Setting | Value |
|---|---|
| Transport | Streamable HTTP, POST only. SSE and stdio are not supported. |
| Authentication | OAuth sign-in, or a workspace API key as a bearer token. |
| Discovery | The 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/mcpand choosesemogramto 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 runcodex 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.
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
See the MCP tools reference for discovery, resource scopes, operation approvals, and asynchronous work.
Rate limits
Requests are limited per minute. Defaults:
| Limit | Default | Applies to |
|---|---|---|
| Organization requests | 600 | All API keys and signed-in assistants in the workspace, combined |
| Requests per key or assistant user | 120 | Each 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
| Symptom | Cause | Fix |
|---|---|---|
401 missing_token or the client asks you to sign in | No token, or the token expired | Sign 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 workspace | Copy 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 key | The key belongs to another workspace | Use a key created in this workspace. |
403 insufficient_scope | The API key lacks projects:read | Create a key with that scope. |
403 workspace_resources_not_allowed | The API key is limited to projects and lacks the Workspace resources grant | Create a key in Settings, then API access, with Workspace resources turned on. |
403 sparql_disabled | Consumer SPARQL access is turned off | An owner or admin turns it on in Settings. |
403 api_key_required | A source_write_* tool was called over OAuth | Connect with an API key that has the data:write scope and a write grant on the endpoint. |
405 on GET | The client tried to open an SSE stream | Expected. The server only accepts POST. |
429 rate_limit_exceeded | Over the per-minute limit | Wait for Retry-After, or raise the limits in Settings. |