MCP integration guideStreamable HTTP · REST v1

Connect your agent to Curated Data

Install the hosted MCP server in your client, authenticate with OAuth or a scoped API token, and retrieve your organization's approved knowledge. Nothing runs on your machine except the MCP client you already use.

Hosted MCP endpoint

https://curateddata.megacorp.company/api/curated-data/mcpPOST only

Before you start

Choose the connection you need

MCP client

Use the hosted MCP endpoint with Claude Code, Cursor, VS Code, or another client that supports remote Streamable HTTP servers. OAuth is recommended for an interactive user.

REST integration

Use the REST v1 API from a service, script, or runtime that is not MCP-native. Mint an API token in organization settings and send it as a bearer token.

The MCP and REST surfaces enforce the same organization, scope, classification, and approval boundaries. Read operations return only the current approved revision; write operations create drafts that still require human review.

Verified hosted surface

This guide is limited to routes present in Curated Data's deployed MCP metadata or hosted REST v1 OpenAPI contract. Paths below are relative to https://curateddata.megacorp.company.

Method	Path	Authentication	Purpose
POST	`/api/curated-data/mcp`	Bearer · read/write	Stateless Streamable HTTP MCP transport.
GET	`/.well-known/oauth-protected-resource/api/curated-data/mcp`	Public	MCP OAuth protected-resource discovery.
GET	`/api/curated-data/v1/openapi.json`	Public	Hosted OpenAPI 3.0 contract for REST v1.
GET	`/api/curated-data/v1/search`	Bearer · read	Search approved concepts.
GET	`/api/curated-data/v1/concepts`	Bearer · read	List approved concepts.
GET	`/api/curated-data/v1/concepts/{path}`	Bearer · read	Fetch one approved concept by path.
POST	`/api/curated-data/v1/concepts`	Bearer · write	Create a concept as a draft revision.
PUT	`/api/curated-data/v1/concepts/{path}`	Bearer · write	Create or update the path's open draft.

Authentication

OAuth or API token

OAuth for interactive MCP clients

Add the endpoint without a token. A compatible client discovers Curated Data's OAuth metadata, opens a browser, and asks you to sign in. Select the organization, scopes, and classifications the client may access, then approve the grant. Access tokens are refreshed by the client; you can revoke a connected client from Settings → MCP.

API token for REST or token-only clients

1
Sign in and open your organization
If you do not have a workspace yet, create one free.
2
Open Settings → API Tokens
Choose New token and give it a name that identifies the integration.
3
Choose the least access required
Select read for search, list, and fetch. Add write only if the integration must propose changes. Limit the token to the classifications it should see, and set an expiry when appropriate.
4
Copy the secret immediately
Tokens begin with ckd_live_. The full secret is shown once; store it in your secret manager. Rotation invalidates the previous secret immediately.

shell — keep the token out of source control

# Set this in your shell or deployment secret manager.
export CURATED_DATA_TOKEN="ckd_live_••••••••"

MCP setup

Install the remote server in your client

Claude Code with OAuth

Add the HTTP server, then authenticate from /mcp inside Claude Code or run claude mcp login curated-data.

terminal — Claude Code (recommended)

claude mcp add --transport http curated-data \
  https://curateddata.megacorp.company/api/curated-data/mcp

# Then authenticate in a browser:
claude mcp login curated-data

Claude Code with an API token

Use this fallback for non-interactive environments or when you deliberately want a long-lived scoped token instead of an OAuth grant.

terminal — Claude Code with bearer token

claude mcp add --transport http curated-data https://curateddata.megacorp.company/api/curated-data/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Cursor or another .mcp.json client

Add a remote HTTP server entry. The exact config-file location is client-specific; use a user-level file for personal credentials and do not commit a literal token.

.mcp.json — remote Streamable HTTP

{
  "mcpServers": {
    "curated-data": {
      "type": "http",
      "url": "https://curateddata.megacorp.company/api/curated-data/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

VS Code

Run MCP: Open User Configuration for a personal connection or create .vscode/mcp.json for a workspace connection. An input variable keeps the token out of the file.

.vscode/mcp.json — prompted bearer token

{
  "inputs": [{
    "type": "promptString",
    "id": "curated-data-token",
    "description": "Curated Data API token",
    "password": true
  }],
  "servers": {
    "curated-data": {
      "type": "http",
      "url": "https://curateddata.megacorp.company/api/curated-data/mcp",
      "headers": {
        "Authorization": "Bearer ${input:curated-data-token}"
      }
    }
  }
}

Local stdio bridge (npx)

No hosted-URL config to manage: install curated-data-mcp, a small npm package that runs locally over stdio and forwards every tool call to the REST v1 API using an API token. Use it for clients that only support local/stdio servers, or when you want a pinned, auditable local process instead of a remote connection.

terminal — Claude Code, local stdio bridge

claude mcp add --transport stdio \
  --env CURATED_DATA_API_TOKEN=ckd_live_... \
  curated-data -- npx -y curated-data-mcp

.mcp.json — local stdio bridge

{
  "mcpServers": {
    "curated-data": {
      "command": "npx",
      "args": ["-y", "curated-data-mcp"],
      "env": {
        "CURATED_DATA_API_TOKEN": "ckd_live_..."
      }
    }
  }
}

Before wiring it into a client, verify the token and network path:

terminal — verify credentials before connecting

CURATED_DATA_API_TOKEN=ckd_live_... npx -y curated-data-mcp --check

The bridge cannot see a token's scopes before a call reaches the API, so it advertises the full tool list unconditionally and lets the hosted API return a 403 for any tool the token's scope does not cover — the same enforcement the hosted MCP and REST surfaces use. Node.js 22 or newer is required.

Client-specific configuration changes over time. See the official Claude Code MCP guide or VS Code MCP guide for the current client UI and config locations.

First request

Verify the connection

A connected MCP client discovers tools automatically. To test the transport yourself, send a JSON-RPC tools/list request. The server is stateless, so every request carries its own bearer token and no Mcp-Session-Id is required.

terminal — list MCP tools

curl https://curateddata.megacorp.company/api/curated-data/mcp \
  -X POST \
  -H "Authorization: Bearer $CURATED_DATA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

To exercise retrieval, call search_knowledge. MCP tool payloads are returned inside a content array; the text item contains the JSON result.

terminal — call search_knowledge

curl https://curateddata.megacorp.company/api/curated-data/mcp \
  -X POST \
  -H "Authorization: Bearer $CURATED_DATA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_knowledge",
      "arguments": { "query": "YOUR_QUERY", "limit": 5 }
    }
  }'

Reference

Available MCP tools

Tool	Scope	Purpose
`search_knowledge`	read	Full-text search across approved concepts.
`get_concept`	read	Fetch one approved concept by path, including its links.
`list_concepts`	read	List approved concepts with type, tag, cursor, and limit filters.
`recommend_knowledge`	write	Turn source material into proposed concept changes for human review.
`ingest_source`	write	Queue a URL crawl or raw text for asynchronous drafting.
`suggest_update`	write	Submit a missing or changed fact to the curation workflow.
`get_import`	write	Poll an ingestion or suggestion job for status and results.
`propose_concept`	write	Create a new concept as a draft revision.
`update_concept`	write	Update a concept's open draft revision.
`import_file`	write	Import a document file (.pdf, .docx, .pptx, .html, .md, .txt) into the drafting pipeline.
`start_import`	write	Start processing an import job once its uploaded file bytes are in place.
`list_review_queue`	approve	List revisions awaiting review, or the rejection backlog.
`get_review`	approve	Read one in-review revision plus the approved baseline to diff against.
`approve_revision`	approve	Approve an in-review revision, publishing it as the live document.
`reject_revision`	approve	Reject an in-review revision with a required note explaining what must change.

Write scope does not grant publish or approval rights. Every MCP write creates or updates a draft; a human reviewer must approve it before read tools or REST reads can return it.

REST v1

Connect without MCP

Use the same API token in the standard Authorization: Bearer header. The base URL is https://curateddata.megacorp.company/api/curated-data/v1. REST reads require read; create and update operations require write.

terminal — search approved knowledge

CURATED_DATA_QUERY='YOUR_QUERY'

curl --get 'https://curateddata.megacorp.company/api/curated-data/v1/search' \
  -H "Authorization: Bearer $CURATED_DATA_TOKEN" \
  --data-urlencode "q=$CURATED_DATA_QUERY" \
  --data-urlencode 'limit=5'

terminal — list and fetch concepts

# List approved concepts
curl 'https://curateddata.megacorp.company/api/curated-data/v1/concepts?limit=25' \
  -H "Authorization: Bearer $CURATED_DATA_TOKEN"

# Fetch a path returned by list or search
CURATED_DATA_CONCEPT_PATH='YOUR_CONCEPT_PATH'
curl "https://curateddata.megacorp.company/api/curated-data/v1/concepts/$CURATED_DATA_CONCEPT_PATH" \
  -H "Authorization: Bearer $CURATED_DATA_TOKEN"

terminal — schema-valid draft example (write scope)

curl 'https://curateddata.megacorp.company/api/curated-data/v1/concepts' \
  -X POST \
  -H "Authorization: Bearer $CURATED_DATA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "concepts/example.md",
    "frontmatter": {
      "title": "Example concept",
      "type": "concept",
      "classification": "internal"
    },
    "body": "# Example concept\n\nReplace this example with your proposed content."
  }'

Search text and concept paths are tenant data, not global Curated Data resources. Use a path returned by your own organization's list or search response. The write example above is schema-valid and creates a draft; do not run it unless you intend to create that draft in your workspace.

Machine-readable API contract

Generate a client or inspect every request and response schema in OpenAPI 3.0.

openapi.json

Operations

Errors, rate limits, and troubleshooting

401

The bearer token is missing, invalid, expired, or revoked. OAuth clients should reconnect or re-authenticate.

403

The principal lacks the required scope or current workspace permission, or a write requests a classification outside the token allowance.

404

The approved concept or job is not available to this principal. Reads hide inaccessible classifications as not found.

405

The MCP endpoint accepts POST only. Do not open a GET/SSE stream or send DELETE.

429

A token or organization rate window is exhausted. Wait for the Retry-After value before retrying.

503

The service is temporarily unavailable. Retry with bounded exponential backoff.

A 429 response supplies Retry-After, RateLimit-Policy, and RateLimit. Use the returned values rather than assuming a fixed quota or retry delay.

No tools appear: confirm the client is configured for HTTP/Streamable HTTP, then restart or refresh its MCP servers.
Search returns nothing: confirm at least one matching revision is approved and its classification is allowed by the token.
OAuth loops or expires: re-authenticate from the client, or revoke the old grant in Settings → MCP and connect again.
A write tool is denied: mint or authorize write scope; read scope cannot create drafts.

Production checklist

Keep credentials and access narrow

Prefer OAuth for a person using an interactive MCP client; use an organization service token for unattended workloads only when an admin has approved that ownership model.
Never put a ckd_live_ secret in source control, screenshots, logs, prompts, or a shared MCP config file. Use your client's secure input support or a secret manager.
Grant read unless the integration genuinely needs to propose drafts. Limit classifications to the smallest useful set.
Use a separate token or OAuth grant for each integration so usage, rotation, and revocation have a clear owner.
Rotate suspected credentials immediately. Rotation and revocation take effect without waiting for a cache or deployment.

Ready to connect?

Create a workspace, approve your first concept, then use OAuth or mint a scoped API token from organization settings.

Create a workspace Sign in