Skip to main content
POST
/
api
/
v1
/
storage
/
sandboxes
/
{sandbox_id}
/
sources
/
user-mcp
Register a tenant-supplied MCP server as a user_mcp source
curl --request POST \
  --url https://api.copass.id/api/v1/storage/sandboxes/{sandbox_id}/sources/user-mcp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "base_url": "<string>",
  "auth_kind": "<string>",
  "token": "<string>",
  "auth_header": "<string>",
  "app_namespace": "<string>",
  "allowed_tools": [
    "<string>"
  ],
  "ingest_tool_calls": [
    {}
  ],
  "rate_cap_per_minute": 60,
  "webhook_rate_cap_per_minute": 600
}
'
{
  "data_source_id": "<string>",
  "status": "<string>",
  "name": "<string>",
  "ingestion_mode": "<string>",
  "health_error": "<string>",
  "error": "<string>",
  "detail": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
authorization
string | null
​
X-Encryption-Token
string | null
​
X-Encryption-Key
string | null

Path Parameters

​
sandbox_id
string
required

Body

application/json

Tenant-supplied MCP server registration payload.

​
name
string
required

Human-readable source name.

​
base_url
string
required

User's MCP server URL (no trailing slash). https only — http rejected except for localhost in dev.

​
auth_kind
string
required

bearer | header_token | none.

​
token
string | null

Bearer / header secret. Required iff auth_kind != 'none'. Stored in vault, never echoed back.

​
auth_header
string | null

Required iff auth_kind='header_token'.

​
app_namespace
string | null

Tool-name prefix (≤64 chars). Defaults to data_source_id when absent. Must be unique across the sandbox's active user_mcp sources.

​
allowed_tools
string[] | null

Per-source allowlist on top of the agent-level one.

​
ingest_tool_calls
Ingest Tool Calls · object[] | null

Tool calls to run on every pull(). Empty = live-tools-only; the source contributes to agent turns but not graph ingestion.

​
rate_cap_per_minute
integer
default:60

Per-source tool-call rate cap. Default 60, max 600.

​
webhook_rate_cap_per_minute
integer
default:600

Per-source webhook firehose rate cap. Default 600, max 6000.

Response

Successful Response

Outcome shape for the three user_mcp lifecycle endpoints.

Mirrors the dict the service methods return verbatim (status, optional health_error, etc.) without re-shaping. error is populated on validation failure; data_source_id is populated on success.

​
data_source_id
string | null
​
status
string | null
​
name
string | null
​
ingestion_mode
string | null
​
health_error
string | null
​
error
string | null
​
detail
string | null