MCP server

Talkif runs a Model Context Protocol server. Every operation in the API Reference is a tool on it, so an AI agent can read your calls, edit and publish flows, load contacts or start a campaign from a chat — with exactly the same checks as a direct API call.

Connect with an API key

Create a key under Developer → Credentials with the scopes the agent needs — see Authentication. The key decides what the agent can do, so give an agent the narrowest key that does the job: calls:read for “which calls failed today?”, flows:* to let it edit voice agents.

claude mcp add --transport http talkif https://api.talkif.ai/api/v1/mcp \
  --header "Authorization: Bearer $TALKIF_API_KEY"

Tools

Each tool is one API operation. Its name is the operation’s ID — the last part of the endpoint’s API Reference URL, with underscores: list_calls is /api-reference/calls/list-calls — and its input is the operation’s path and query parameters plus, for requests with a body, a body argument holding the JSON body. The browser endpoints that use a publishable key are not tools.

A key sees only what its scopes reach. tools/list leaves out every tool whose endpoint the key’s scopes don’t cover, so an agent with a calls:read key never sees make_call. A tool call runs through the endpoint itself, so the scope, the IP allowlist, the role of the key’s creator and the endpoint’s own limits are all checked again on every call.

Two options on the URL narrow the list further:

The toolsets are the API Reference sections: ai_models, analytics, billing, calls, campaigns, contacts, do_not_call, errors, flow_functions, flow_templates, flows, phone_numbers, phone_providers, schedules, transfers.

Tools that cost money or reach people

These tools spend from your balance, dial or reach people outside the account, or change what live callers hear. Their description says “confirm with the user first”, and they carry the MCP openWorldHint annotation so clients can ask before running them:

Every other tool that changes data says “Changes data” or “Deletes data” in its description and carries destructiveHint. Read tools carry readOnlyHint. Whether a client asks before running a tool is the client’s setting — Talkif marks the tools, it cannot make a client ask.

Results

A tool returns the API’s JSON response as text. When the API answers with an error, the tool result has isError: true and the text is the API’s error body — the agent reads code the same way your code would. Results longer than 60,000 characters are cut with a note telling the agent to page with limit / offset or a narrower filter.

Each MCP request counts once in the key’s usage under Developer → Credentials, and a tool call that fails appears in the key’s recent errors with the endpoint it called.

Limits

Listing tools and other non-call methods don’t count toward the 60. An agent that hits the limit is usually fetching item by item; tell it to list with filters instead.

There is no idempotency key on tool calls. An agent that retries make_call after a timeout can place a second call — the same rule as for the API applies: look in list_calls before retrying (see Retrying safely).

Errors

Sign in with Talkif

Some MCP clients take only a server URL and cannot send an API key. For those, the server supports OAuth 2.1: the client sends you to the Talkif dashboard, you approve it for one account, and the client gets a token of its own. In the dashboard these approvals are called connected apps.

What you need

• Connectors turned on for the account. An owner or admin does this once in Developer → Integrations. Until then, approving an app is refused with “Connectors are off for this account”.
• To be an owner, admin or member of the account you connect the app to.

Approving an app

1. Add https://api.talkif.ai/api/v1/mcp to the app as a server URL. The app opens a Talkif page in your browser.
2. Sign in to the dashboard if you aren’t already. The page shows the app’s name, the address you’ll be sent back to, and what the app will be able to do. Talkif does not verify app names — allow only an app you just added yourself from that address.
3. Choose the account the app works in (it works in that one account only), optionally name the connection, and select Allow. You’re sent back to the app.

A request you don’t answer expires after 10 minutes; start again from the app.

What a connected app reaches

The app acts as the person who approved it, with that person’s current role in the account — not only their own sessions:

Agents can’t approve apps. A session whose client doesn’t tell Talkif who is asking stays reachable by its owner only. The role is checked on every request: lowering someone’s role narrows their apps at once, and removing them from the organization stops them. Approve an app as an owner or admin only when it should reach the whole organization.

Connected apps

Developer → Integrations → Connected apps lists the apps connected to the account, with when each was connected and last used. Members see the apps they connected; owners and admins see everyone’s.

• Disconnect revokes the app at once: its tokens stop working and it has to be connected again. Owners and admins can disconnect anyone’s app.
• Only the person who connected an app can rename it or, in an organization, choose who else can reach it.
• Changing or resetting your password, and signing out everywhere, disconnects all your apps.
• An app also stops working when its person leaves the account or the account is scheduled for deletion.

For client developers

The server follows the MCP authorization spec. A client discovers everything from the 401 it gets without a token:

The rules a client must follow:

• Public clients only. Register with token_endpoint_auth_method: "none"; there is no client secret. Grant types authorization_code and refresh_token, response type code.
• PKCE with S256 on every authorization request. Plain PKCE and requests without a challenge are refused.
• Redirect URIs are matched exactly: https:// with a real host name, or http://localhost / 127.0.0.1 / [::1] with a port. No fragments, no user info, at most 5 per client.
• Scope is talkif, the only one; omitting scope asks for it. resource, when sent, must be https://api.talkif.ai/api/v1/mcp.
• The authorization response carries iss (RFC 9207), so a client can check which server answered.
• client_name is what the consent page shows. It may not contain “Talkif”.

Tokens:

Every refresh returns a new pair and retires the old refresh token. Presenting a used refresh token again within 24 hours, or reusing an authorization code, revokes the whole connection — the person has to approve the app again. Send the access token as Authorization: Bearer tif_oat_…; it is accepted only by the MCP server and the endpoints an API key could call, never by the dashboard’s own endpoints.

The OAuth endpoints answer errors in the OAuth format ({"error", "error_description"}), not the API’s error body. They are rate-limited: 20 registrations per hour per IP address, 30 authorization requests per 10 minutes per IP address, and 600 token requests per hour per client (30 per connection).

Next