MCP action tools

Let AI agents call the TFUAI public API through a scoped remote MCP server.

TFUAI has two separate MCP interfaces. They solve different jobs.

Interface	URL	Purpose
Documentation search MCP	https://teamfollowupai.mintlify.site/mcp	Search and read these docs
API action MCP	https://api.teamfollowup.ai/api/mcp	Call published TFUAI API operations

Mintlify provides the documentation search MCP. It does not turn OpenAPI operations into callable action tools. Use the API action MCP when an agent needs live TFUAI data.

Connect

Setting	Value
Transport	Streamable HTTP
Server URL	https://api.teamfollowup.ai/api/mcp
Authentication	OAuth 2.1, or a bearer API key

The endpoint accepts either credential. Pick by how the client runs:

• OAuth suits hosted assistants such as Claude, ChatGPT, and Gemini. The user signs in and approves the scopes in a browser, so no secret is ever pasted into a chat. Most clients only need the server URL.
• API keys suit scripts, backend jobs, and self-hosted clients where no person is present to approve a browser prompt.

OAuth

Point the client at https://api.teamfollowup.ai/api/mcp and let it run discovery. An unauthenticated request returns 401 with the pointer that starts the flow:

WWW-Authenticate: Bearer realm="TFUAI MCP",
  resource_metadata="https://api.teamfollowup.ai/.well-known/oauth-protected-resource/api/mcp"

From there the client reads the metadata, registers itself, and opens the consent screen. The endpoints exist if you need them directly:

Endpoint	Purpose
/.well-known/oauth-protected-resource/api/mcp	Which authorization server protects this endpoint
/.well-known/oauth-authorization-server	Authorization server metadata
/register	Dynamic client registration
/authorize	Authorization request and consent
/token	Token issue and refresh
/revoke	Token revocation

What to expect during the flow:

• PKCE is required, S256 only. A request without a code challenge is refused.
• The consent screen lists the exact scopes the client asked for. Anything the user does not grant is not issued.
• Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use, so a refresh token is only ever valid once.
• Reusing a spent refresh token or authorization code revokes that whole token family. This is the standard response to a stolen token, and it means the client must store the newest refresh token it received.

Revoke a connection at any time from the dashboard, or by calling /revoke.

API keys

Send the key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Create a narrowly scoped key from the API Keys page in the dashboard. Do not put a key in a prompt, repository, browser bundle, screenshot, or support message.

Tool results can contain contact details, call records, billing data, and other tenant information. Connect the MCP only to clients approved to receive that data, request only the modules needed for the task, and avoid broad exports when a narrower read answers the question.

You can verify the connection with an MCP initialize request:

curl --request POST \
  --url https://api.teamfollowup.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json, text/event-stream" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

The negotiated protocol version in the response can be newer than the version in this example.

Tool visibility

tools/list returns only tools that meet both conditions:

1. The operation is enabled for the current MCP release.
2. The credential carries the operation’s required scope.

This applies the same way to an API key’s scopes and to the scopes a user granted an OAuth client. A module write scope also covers its matching read scope. Public read operations can appear for any valid credential.

Filtering is not only cosmetic. A tool the credential lacks the scope for is hidden from tools/list and refused if called by name.

For broad credentials, narrow the advertised catalog with a comma-separated module filter. Module names are lowercase tag slugs:

https://api.teamfollowup.ai/api/mcp?modules=contacts,calls

This reduces the number and size of tool definitions sent to the agent. An unknown module returns HTTP 400 with the valid module names.

Reads and writes

The MCP advertises every published read operation, plus the write operations whose effect stays inside the platform. A credential with agents:write can create, update and delete agents; one with campaign_workflows:write can edit workflows.

Write tools carry standard MCP annotations so your client knows when to ask before running one:

Annotation	Meaning
readOnlyHint: true	The tool only reads
destructiveHint: true	The call overwrites or removes existing state
idempotentHint: true	Repeating the call has the same effect as making it once

A create is annotated destructiveHint: false. An update or delete is destructiveHint: true.

Most operations do not accept an Idempotency-Key. If a tool call times out, a retry can repeat the write. Prefer reading current state back before retrying a create.

Operations the MCP does not expose

Some published operations are deliberately absent from tools/list, no matter how broad the key is. They place calls to real people, spend money, or cannot be undone, and the consequence of a model getting one wrong does not stay inside the platform:

Area	Why it is withheld
calls:write	Places real outbound calls
power_dialer:write	Starts or changes live dialling of a lead list
phone_numbers:write, phone_numbers:release	Buys numbers, and releasing one is irreversible
projects:write, projects:delete	Overwrites or destroys a project
Clearing a contact’s do-not-call flag	Can produce a call that should not be placed. Setting the flag is available
Enrolling existing leads into a campaign	Puts contacts in line to be dialled

Call these through the REST API, where a person is making the request. The tools stay withheld rather than being scope-gated because the risk is about who is deciding, not about what the key is allowed to do.

Tool arguments

Tool schemas preserve the original OpenAPI parameter locations:

{
  "path": {},
  "query": {},
  "headers": {},
  "body": {}
}

Only groups used by an operation appear in that tool’s schema, and each schema lists the groups it actually requires. A group the schema does not require can be left out entirely rather than sent as an empty object. For example, deleting an agent skill takes only path, because the optional expectedVersion in its body is the sole thing a body would carry.

A contact call-history read can accept:

{
  "path": {
    "phoneNumber": "[phone]"
  },
  "query": {
    "projectName": "Riverside Clinic",
    "contactId": "contact_123"
  }
}

The server validates arguments before the API request. It controls the request URL and authentication header, so an agent cannot supply an arbitrary URL or forward arbitrary headers.

Results

• Every operation published today answers with JSON, which returns as both MCP text content and structured content.
• Public API errors return tool results with isError: true and the original safe error body. The HTTP status is on the result as _meta["tfuai/httpStatus"].
• Network failures, timeouts, and oversized responses fail as tool errors.

CSV exports and logo reads are not part of the published surface, so no tool returns text or image content. If a module publishing either is added later, the adapter already carries them through as MCP text and image content.

Every tool call goes through the same public REST route as a direct API call. Credential validation, scopes, tenant access, role checks, rate limits, and public response projections still apply.

Common connection errors

Result	Meaning
HTTP 401 before JSON-RPC	Missing, invalid, expired, or revoked credential. The WWW-Authenticate header names the authorization server, so an OAuth client can recover by refreshing or reconnecting
invalid_grant on refresh	The refresh token was already spent. Reconnect through the consent screen
Tool is absent from tools/list	Missing scope or operation not enabled for MCP
Tool result has HTTP 403	The public route rejected role, tenant, project, or scope access
Tool result has HTTP 429	A public API rate limit was reached

Use the Authentication page for scopes and key management.