Connect a Context MCP server | Dial — Communication Stack for AI Agents

curl -X POST https://api.getdial.ai/api/v1/context-mcps \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Acme MCP Server",
  "url": "https://mcp.acme-corp.com/api"
}'

{
  "contextMcp": {
    "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    "name": "Acme MCP Server",
    "url": "https://mcp.acme-corp.com/api",
    "authMode": "oauth",
    "status": "pending_auth",
    "toolCount": 3,
    "timeoutMs": 120000,
    "headersMasked": {},
    "queryParams": {},
    "lastError": "Waiting for user consent",
    "createdAt": "2024-01-15T09:30:00Z"
  },
  "authorizationUrl": "https://auth.acme-corp.com/oauth2/authorize?client_id=abc123&response_type=code&scope=openid%20profile&redirect_uri=https%3A%2F%2Fapi.getdial.ai%2Foauth%2Fcallback"
}

Registers an MCP server and wires its tools into the account’s voice agent. Dial probes the server’s URL to determine how it authenticates:

Unauthenticated or static — the connection is wired immediately and returned with status: "connected".
OAuth 2.1–protected — the response includes an authorizationUrl and status: "pending_auth". Open that URL in a browser to grant consent; Dial completes the connection on the OAuth callback and then manages token refresh for you. The server’s authorization server must support Dynamic Client Registration (RFC 7591).

If the server is unreachable, or responds to the probe with a server error (HTTP 5xx), the request is rejected with 400 and a message naming the status Dial observed — the fault is on your server, so fix it and try again.

Registers an MCP server and wires its tools into the account's voice agent. Dial probes the server's URL to determine how it authenticates: - **Unauthenticated or static** — the connection is wired immediately and returned with `status: "connected"`. - **OAuth 2.1–protected** — the response includes an `authorizationUrl` and `status: "pending_auth"`. Open that URL in a browser to grant consent; Dial completes the connection on the OAuth callback and then manages token refresh for you. The server's authorization server must support Dynamic Client Registration (RFC 7591). If the server is unreachable, or responds to the probe with a server error (HTTP 5xx), the request is rejected with `400` and a message naming the status Dial observed — the fault is on your server, so fix it and try again.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Request

This endpoint expects an object.

namestringRequired

Display name for the connection.

urlstringRequiredformat: "uri"

HTTPS MCP server URL (http allowed only for localhost in development).

headersmap from strings to stringsOptional

Extra static headers to send on every connection. For an OAuth-protected server, any Authorization header you set is ignored — Dial manages it.

queryParamsmap from strings to stringsOptional

Query parameters to append to the connection URL.

timeoutMsintegerOptional

Connection timeout in ms. Defaults to 120000.

Response

The created connection. For OAuth servers, authorizationUrl is present and the connection stays pending_auth until consent completes.

contextMcpobject

authorizationUrlstring or nullformat: "uri"

Present only for OAuth-protected servers. Open in a browser to grant consent and finish connecting.

Errors

400

Bad Request Error

401

Unauthorized Error

Registers an MCP server and wires its tools into the account’s voice agent. Dial probes the server’s URL to determine how it authenticates:

Unauthenticated or static — the connection is wired immediately and returned with status: "connected".
OAuth 2.1–protected — the response includes an authorizationUrl and status: "pending_auth". Open that URL in a browser to grant consent; Dial completes the connection on the OAuth callback and then manages token refresh for you. The server’s authorization server must support Dynamic Client Registration (RFC 7591).