---
title: "Connect a Context MCP server"
method: POST
path: "/api/v1/context-mcps"
tags: ["contextMcp"]
---

# Connect a Context MCP server

`POST /api/v1/context-mcps`

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.

## Headers

- `Authorization` string, required

## Request body

- CreateContextMcpRequest
  - `name` string, required — Display name for the connection.
  - `url` string, uri, required — HTTPS MCP server URL (http allowed only for localhost in development).
  - `headers` object — Extra static headers to send on every connection. For an OAuth-protected server, any `Authorization` header you set is ignored — Dial manages it.
  - `queryParams` object — Query parameters to append to the connection URL.
  - `timeoutMs` integer — Connection timeout in ms. Defaults to 120000.

## Response `201`

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

- ContextMCPCreateContextMcpResponse201
  - `contextMcp` ContextMcp, required
    - `id` string
    - `name` string
    - `url` string, uri — The MCP server URL.
    - `authMode` 'none' | 'static' | 'oauth' — How the server authenticates, detected on connect. `none`: unauthenticated. `static`: fixed headers you supplied. `oauth`: OAuth 2.1, with tokens managed by Dial.
    - `status` 'pending_auth' | 'connected' | 'error' — `pending_auth`: awaiting OAuth consent. `connected`: tools are wired to the agent. `error`: connection or token refresh failed (see `lastError`).
    - `toolCount` integer — Number of MCP tools wired into the agent.
    - `timeoutMs` integer, nullable — Connection timeout in ms; null uses the default (120000).
    - `headersMasked` object — Extra static request headers, with values masked. The OAuth-managed `Authorization` header is never returned.
    - `queryParams` object — Query parameters appended to the connection URL, with values masked.
    - `lastError` string, nullable
    - `createdAt` string, date-time
  - `authorizationUrl` string, uri, nullable — Present only for OAuth-protected servers. Open in a browser to grant consent and finish connecting.

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/versions/cfa621230237/schema)