Back to Documentation

Sutram MCP Server User Guide

Connect Sutram to Claude (and other MCP-compatible clients) so you can query, summarize, and edit your project content in natural language.

At a glance

You're using Use this path
Claude.ai (web) or Claude Desktop with Custom Connectors OAuth Custom Connector — one click, no API keys
Claude Code (CLI), Cursor, or older Claude Desktop builds API key bridge — paste a config file with two keys

Both paths talk to the same Sutram MCP server and expose the same tools. Pick whichever your client supports best.

Plan requirement: MCP access requires a Sutram subscription on the Pro plan or higher. The Basic plan does not include MCP.

Path A — OAuth Custom Connector (recommended)

1. Open the Connectors panel in Claude

In Claude.ai (or Claude Desktop with Custom Connector support):

  1. Open Settings (gear icon) → Connectors
  2. Click Add custom connector

2. Add the Sutram URL

  • Name: Sutram (or any label you like)
  • URL:
https://app.sutram.io/mcp/v2

Click Add.

3. Connect and authorize

Click Connect. Claude opens a browser window to https://app.sutram.io/mcp/v2/oauth/authorize.

  • If you're already logged into Sutram, you go straight to the consent screen.
  • Otherwise, sign in to Sutram first; you land on the consent screen automatically.

The consent screen asks you to pick the project the connector should reach. The OAuth token is scoped to that single project — pick carefully.

Click Authorize.

You're redirected back to Claude with the connector showing as connected.

4. Allow the network (one-time, until directory listing is live)

Claude.ai keeps an outbound network allowlist. MCP traffic to app.sutram.io is allowed by default, but file downloads come from a CDN and file uploads go straight to S3 — both need explicit authorization once:

  1. Settings → Capabilities → Code Execution and File Creation (section names vary by Claude build; look for the outbound network allowlist)
  2. Under Additional allowed domains, add all three:
    • app.sutram.io — MCP endpoint, OAuth, discovery
    • files.sutram.io — file downloads (CloudFront edge)
    • s3.amazonaws.com — direct file uploads (presigned URL endpoint)

Once Sutram is listed in the Anthropic Connectors Directory, these three hosts are declared in the listing and clients authorize them automatically.

5. (Optional) Apply the Sutram Assistant Preset

Without the preset, Claude works — but it may occasionally ask you to "attach a file" or "connect a folder" when you mean a Sutram document, because it hasn't been told what context to assume.

To make Claude Sutram-aware by default, copy the System Prompt from the Sutram Assistant Preset page and paste it into your Claude project's Custom Instructions (Personalization / Project System Prompt — name varies by client).

After this, prompts like "Summarize my latest cardiology exam" go straight to the Sutram connector instead of asking you to upload anything.

6. Try a starter prompt

Open a new conversation and ask:

Show me an overview of my project and what's in it.

Claude calls sutram_project_info and sutram_get_folder in sequence and returns a structured summary of your project root.

Path B — API key bridge (Claude Code, Cursor, older Claude Desktop)

Use this when your client doesn't yet support Custom Connectors (Claude Code CLI, Cursor, older Claude Desktop builds, or local development against a non-public Sutram instance).

1. Create your personal API key

Settings → Integrations → Claude → click Generate user key.

Your personal key looks like:

sk_user_…

Copy it once — it's not retrievable later.

2. Get the project key

The project owner must first enable MCP access for the project:

Project Settings → Integrations → toggle Enable MCP access ON.

Once enabled, any project member (owner, admin, or member) can copy the project key from the same screen:

sk_proj_…

3. Configure your client

The same JSON block works in all three clients — only the file location changes.

{
  "mcpServers": {
    "sutram": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.sutram.io/mcp",
        "--header",
        "Authorization: Bearer dualkey:sk_proj_...:sk_user_..."
      ]
    }
  }
}

Replace sk_proj_... and sk_user_... with your real keys.

The Authorization header must be a single line — JSON does not allow control characters inside string literals.

Claude Code (CLI) — recommended

Create the JSON above as .claude/mcp.json in your workspace folder. Start Claude Code from that folder; Sutram tools are scoped to that workspace.

Cursor

Create the JSON above as .cursor/mcp.json in your project folder.

Claude Desktop (older builds)

Edit the global config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the mcpServers block alongside any existing keys. Restart Claude Desktop.

4. Try a prompt

Show me an overview of my Sutram project.

API key bridge clients don't enforce a host allowlist, so file downloads work without further configuration.

Troubleshooting

Symptom Likely cause Fix
"Couldn't reach the MCP server" at first connect Connector tried OAuth discovery and got blocked by the allowlist Confirm app.sutram.io is reachable: curl -I https://app.sutram.io/mcp/v2 should respond. If yes, revisit Path A, step 4.
Consent screen shows but Authorize returns to a 500 Server-side error on consent persistence Outage. Contact support@sutram.io with the timestamp.
Connector shows as connected, but tool calls return 401 Access token expired (1-hour TTL) Retry the prompt — Claude refreshes automatically via the refresh token. If it fails again, click Reconnect on the connector.
Claude replies "I don't have access to any folder on your computer" Claude interpreted a generic prompt as a filesystem request Be explicit ("…on Sutram"), or apply the Assistant Preset (Path A, step 5).
File reads fail with "network blocked" app.sutram.io is allowed but files.sutram.io isn't Add files.sutram.io to the allowlist (Path A, step 4).
OAuth flow loops back to the login page Browser blocking third-party cookies for the consent popup Try Firefox or Chrome, or temporarily disable strict tracking protection in Safari.

What Sutram exposes

Once connected, Claude has access to roughly 50 tools, grouped into:

  • Discovery (read-only): sutram_project_info, sutram_get_folder, sutram_search_items, sutram_search_folders, sutram_get_item, sutram_list_comments, sutram_list_versions, sutram_get_record_categories, and related queries.
  • Editing: sutram_create_folder, sutram_create_record, sutram_create_web_link, sutram_create_comment, sutram_set_item_tags, sutram_rename, sutram_move_item, and similar.
  • File workflow: sutram_request_upload, sutram_confirm_upload, sutram_checkout_file, sutram_checkin_file, sutram_create_new_version, sutram_publish_version.
  • Custom record types: sutram_upsert_record_category, sutram_upsert_metadata, sutram_add_enum_values.

Read-only tools may be auto-approved by your client. Destructive tools (sutram_delete, sutram_delete_record, sutram_force_release_lock) always ask for explicit confirmation per call.

Resources

Back to Documentation