MCP server

Endpoint and authentication

• Streamable HTTP at https://contents.team/api/mcp.
• Authenticate with an org API key as a bearer token, exactly as for the REST API. Each tool needs the scopes listed below, so give an assistant's key only what you want it to do. A ctk_test_ key is a safe place to start.
• OAuth access tokens (cto_) work too. A request without a valid credential gets a 401 whose WWW-Authenticate header points at /.well-known/oauth-protected-resource/api/mcp, so OAuth-capable clients find the authorization server on their own.
• The server is stateless: every call is a plain POST with JSON back, and there are no sessions to keep alive.
• The tools call the same operations as the REST API, with the same scopes, limits, ids, cents and basis points. A test key's add_photos uses the fixture pipeline; send X-Contents-Test-Mode: live-ai on the connection to use the real one, as on REST.
• export_report waits up to 20 seconds for the file. If it is not ready by then, call it again with the returned exportId.

Tools

Retries

create_claim, add_photos and export_report take an optional idempotencyKey argument, the MCP form of the REST Idempotency-Key header with the same rules: 1 to 255 visible ASCII characters, kept for 24 hours. Send a new key for each action and the same key when retrying it, and a retry returns the first result instead of making a second claim, batch of photos or export. The same key with different arguments, or on another tool, is a tool error with code idempotency_key_reused; a retry while the first call is still running is idempotency_request_in_progress, so wait a moment and retry. A call that fails frees its key.

Connect a client

Each snippet reads the key from the CONTENTS_API_KEY environment variable. Keep the key out of shared config files and repositories.

Claude Code

claude mcp add --transport http contents-team https://contents.team/api/mcp \
  --header "Authorization: Bearer $CONTENTS_API_KEY"

Then ask Claude Code to create a test claim called JOB-1042 and show me its inventory. Run claude mcp list to check the connection.

Cursor

{
  "mcpServers": {
    "contents-team": {
      "url": "https://contents.team/api/mcp",
      "headers": { "Authorization": "Bearer ${env:CONTENTS_API_KEY}" }
    }
  }
}

Claude Desktop

Claude Desktop starts local servers from its config file, so it reaches a remote server with bearer auth through the mcp-remote bridge. Add this to claude_desktop_config.json and restart the app.

{
  "mcpServers": {
    "contents-team": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://contents.team/api/mcp",
        "--header", "Authorization:Bearer ${CONTENTS_API_KEY}"
      ],
      "env": { "CONTENTS_API_KEY": "ctk_test_..." }
    }
  }
}

Custom connectors on claude.ai and ChatGPT sign in with OAuth rather than a key. They work through OAuth apps, which are in preview; see Authentication.

ChatGPT and the OpenAI API

From your own code, the OpenAI Responses API connects to remote MCP servers and passes the key in a header:

from openai import OpenAI
import os

client = OpenAI()
response = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "contents_team",
        "server_url": "https://contents.team/api/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['CONTENTS_API_KEY']}"},
        "require_approval": "never",
    }],
    input="List my five newest claims and how many items each has.",
)
print(response.output_text)

Good habits

• Give each assistant its own key, so you can see its activity and revoke it alone.
• Leave approval on for the write tools (create_claim, add_photos, export_report, add_item, update_item, delete_item, approve_items, unapprove_items, reject_items and accept_replacement) in clients that ask before calling a tool.
• An assistant drafts, a person approves. Give a key items:write only when a person signs off on what the assistant approves; without it, items still need a reviewer in Contents.team.