Back to Documentation

Connecting Sutram to Claude

Connect Sutram to Claude (and to other MCP-compatible AI assistants) to query, summarize, and edit your project content in natural language.

Overview — two paths

You use Use this path
Claude.ai (web) or Claude Desktop with Custom Connectors OAuth Connector — one click, no API keys
Claude Code (CLI), Cursor, or older versions of Claude Desktop API-key bridge — one config file with both keys

Both paths talk to the same Sutram MCP server and expose the same tools. Choose the one your client supports best. The full tool reference is in the Sutram MCP Server Guide.

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

Path A — OAuth Connector (recommended)

For Claude.ai (web) and Claude Desktop with Custom Connectors support. No need to copy keys — authorization is handled by OAuth.

1. Open the Connectors panel in Claude

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

2. Enter the Sutram URL

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

Click Add.

3. Connect and authorize

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

  • If you are already logged in to Sutram, you go straight to the consent screen.
  • Otherwise, log in to Sutram first; the consent screen appears next.

The consent screen asks you to choose the project the connector will access. The OAuth token is restricted to that single project — choose carefully.

Click Authorize. You return to Claude with the connector marked as connected.

4. Allow the network (once, until the directory listing)

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

  1. Settings → Capabilities (the section name varies by Claude version) → find the outbound network allowlist
  2. Under allowed domains, add all three:
    • app.sutram.io — MCP endpoint, OAuth, and discovery
    • files.sutram.io — file downloads (CloudFront edge)
    • *.s3.amazonaws.com — direct uploads (pre-signed URL)

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

5. (Optional) Apply the Sutram Assistant Preset

Without the preset, Claude still works — but it may, from time to time, ask you to "attach a file" or "connect a folder" when you mean a Sutram document, because it does not know what context to assume.

To make Claude aware of Sutram by default, copy the System Prompt from the Sutram Assistant Preset and paste it into the Custom Instructions of your project in Claude (Personalization / project System Prompt — the name varies by client). After that, requests like "Summarize my latest cardiology exam" go straight to the Sutram connector, without asking for an upload.

6. Test with a starter prompt

Open a new conversation and ask:

Give 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's root.

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

Use this when your client does not yet support Custom Connectors (Claude Code CLI, Cursor, older versions of Claude Desktop, or local development against a non-public Sutram instance).

1. Create your personal API key

Go to Settings → Integrations → Claude and click Generate user key.

Your personal key looks like:

sk_user_…

Copy it right away — it cannot be retrieved later. If you lose it, revoke the old one and generate a new one on the same screen.

2. Get the project key

The project owner must first enable MCP access:

Project Settings → Integrations → turn on Enable MCP access.

After that, any project member (owner, admin, or member) can copy the project key on the same screen:

sk_proj_…

3. Configure your client

The same JSON block works in all three clients — only the file location changes. The bridge uses the mcp-remote package, and both keys go together in a single Authorization header:

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

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

The Authorization header must be on a single line — JSON does not allow line breaks inside strings. The user key (sk_user_…) identifies you and is the same across all projects; the project key (sk_proj_…) changes per project. Requires Node.js (npx downloads mcp-remote on first use).

Claude Code (CLI)

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

Cursor

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

Claude Desktop (older versions)

Edit the global config file and add the mcpServers block alongside the existing entries:

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

Restart Claude Desktop after saving.

4. Test with a prompt

Give me an overview of my Sutram project.

Bridge clients do not enforce a network allowlist, so file downloads work without any extra configuration.

Key security

  • Keys are independent: revoking a user key does not affect other users. Revoking the project key disables remote access for everyone in that project.
  • One project key per project: only one is active at a time; regenerating it invalidates the previous one.
  • Keys are never stored in plain text: project keys are encrypted; user keys are hashed — they cannot be retrieved after creation.
  • HTTPS only: all connections use encrypted HTTPS.

Revoking access

  • Your personal key: Settings → Integrations → Claude → revoke the key.
  • Project MCP access (owner only): Project Settings → Integrations → disable MCP access.

Connection troubleshooting

Symptom Likely cause Fix
"Could not reach the MCP server" on the first connect The connector tried OAuth discovery and was blocked by the allowlist Confirm that app.sutram.io is reachable (curl -I https://app.sutram.io/mcp/v2 should respond). If so, review Path A, step 4.
Consent screen appears, but Authorize returns 500 Server error persisting the consent Instability. Contact support@sutram.io with the time.
Connector connected, but calls return 401 Access token expired (1-hour TTL) Repeat the prompt — Claude renews automatically via the refresh token. If it fails again, click Reconnect.
Claude replies "I don't have access to any folder on your computer" It interpreted a generic prompt as a filesystem request Be explicit ("…in Sutram") or apply the Assistant Preset (Path A, step 5).
File read fails with "network blocked" app.sutram.io is allowed, but files.sutram.io is not Add files.sutram.io to the allowlist (Path A, step 4).
OAuth flow loops back to the login screen Browser blocking third-party cookies in the consent popup Use Firefox or Chrome, or temporarily disable strict tracking protection in Safari.
Tools do not appear in Claude Code / Cursor Misconfigured bridge Confirm that Node.js (npx) is installed and that the file (.claude/mcp.json or .cursor/mcp.json) is in the folder you start the client from.

Resources

  • Sutram MCP Server Guide — the full reference of available tools
  • Sutram Assistant Preset — System Prompt and starter prompts to make Claude aware of Sutram by default
  • Support: support@sutram.io

Document Version: 1.0 Last Updated: July 2026 Author: Sutram Development Team

Back to Documentation