Model Context Protocol

Deeplinq supports MCP in two directions:

1. it exposes a read-only MCP server at /mcp;
2. organizations can register external Streamable HTTP MCP servers and attach their tools to durable agents.

Deeplinq's MCP server

Connect an MCP client to:

https://api.example.com/mcp

Authenticate with the same bearer credential as the HTTP API. The server exposes:

The shipped Deeplinq MCP surface is intentionally read-only.

Register an external MCP server

The endpoint must be reachable from the public internet. The engine dials it through an SSRF egress guard, so an address inside a private network, a loopback address, or a cloud metadata endpoint (169.254.169.254) is refused with 400 — at registration and on every later call, since the check happens when the connection is made rather than when the URL is stored.

An org-admin registers a Streamable HTTP endpoint:

curl -H "Authorization: Bearer $ORG_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/mcp-servers" -d '{
  "slug":"crm",
  "name":"CRM tools",
  "url":"https://mcp.example.com/mcp",
  "bearer":"<external-server-token>"
}'

Registration calls tools/list, stores a deterministic tool snapshot, and seals the bearer. Responses never return the credential.

Tools are namespaced:

mcp/crm/search_customer
mcp/crm/create_note

The organization-unique slug prevents collisions with email or another MCP server.

Refresh the tool snapshot

POST /v1/mcp-servers/{server_id}/sync-tools

Tool lists do not change automatically. Explicit synchronization keeps agent grants deterministic and makes tool removal an auditable operator action.

Browse the member catalog

Any authenticated organization member — administrator or not — can read the member-safe catalog before deciding what to attach:

GET /v1/mcp-servers/catalog

It returns the organization's active servers that currently have at least one tool whose effective policy is not deny, each with the namespaced tool names, descriptions, the allow/require_approval policy, and only the caller's own attachment (attached plus their connection_id, null when unattached). Operator configuration — the server URL, credential metadata, definition hashes, argument schemas, and denied tools — never appears here; that stays on the org-admin surface below.

Attach for a user

Any organization member can attach the registered server:

curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
  -X POST "$BASE_URL/v1/mcp-servers/$SERVER_ID/attach"

This creates a user-owned mcp connection. Revoke it through the ordinary connection API:

DELETE /v1/connections/{connection_id}

Grant an agent tool

{
  "tools": [
    {
      "tool_name": "mcp/crm/search_customer",
      "policy": "auto"
    },
    {
      "tool_name": "mcp/crm/create_note",
      "policy": "requires_approval"
    }
  ]
}

Send this as a complete replacement to:

PUT /v1/agents/{agent_id}/tools

The engine applies the same ownership, approval, durability, guardrail, audit, and result-size controls as built-in connection tools.

MCP tools differ from built-in tools in two places. The first is their default policy. Omit policy on an mcp/… grant and it resolves to requires_approval, because the server behind the tool name is yours to operate, not the engine's — a later sync-tools can legitimately re-point that name at a different description and schema. Unattended execution stays available; it just has to be an explicit "policy": "auto".

The second is what happens when you re-sync. sync-tools records a hash of each tool's name, description and argument schema. If a tool's definition has moved since the last sync — the same name now describing something else — every auto grant for it across your organization drops to requires_approval, and the sync's audit event names the tools that changed. Nothing is demoted when a re-sync finds the definitions unchanged.

Idempotency behavior

External tools are retry-safe only when the server's tool metadata declares idempotentHint. Deeplinq propagates a stable run-derived idempotency key as the JSON-RPC request ID and _meta.

A missing declaration fails closed for ambiguous retries. Text content blocks are supported; other MCP result content types are not currently part of the shipped contract.

Administration

GET    /v1/mcp-servers
GET    /v1/mcp-servers/catalog
GET    /v1/mcp-servers/{id}
DELETE /v1/mcp-servers/{id}
POST   /v1/mcp-servers/{id}/sync-tools
POST   /v1/mcp-servers/{id}/attach

GET /v1/mcp-servers and the item routes are org-admin operations; /catalog and /attach are member-level.

Deleting or disabling a server makes its tools unavailable to runs. A dropped tool cannot execute merely because an older agent grant still names it.