MCP server

Create AI Characters and generate their DM and comment replies from any MCP client.

FluidTalk runs a remote Model Context Protocol server, so an AI agent such as Claude Code, Cursor or Claude Desktop can create and configure characters, bind them to platforms, and hold real conversations. It is the same engine, the same memory and the same billing as the Characters API — the agent just reaches it through MCP tools instead of HTTP endpoints. Like the API, it never posts or sends anything itself: it generates, your connector delivers.

At a glance

Endpoint	https://api-talk.fluidvip.com/mcp
Transport	Streamable HTTP: JSON-RPC 2.0 over a single POST. The server never opens a stream of its own, so GET returns 405 and there is no session to keep alive.
Protocol version	2025-06-18. 2025-03-26 and 2024-11-05 are also accepted: the server answers with the version your client asks for when it supports it, otherwise with 2025-06-18.
Authentication	Authorization: Bearer ftm_... on every request. X-FluidTalk-Key: ftm_... is accepted for clients that keep Authorization for their own sign-in flow.
Tools	48, of which 7 spend tokens. tools/list returns the live catalogue with each tool's input schema.

Get a key

MCP keys are created in the dashboard, not through the API:

1. Sign in at talk.fluidvip.com and choose MCP in the sidebar (under Account).
2. Under Keys, give the key a name (one per agent or machine works best) and select Create key.
3. Copy the ftm_... key straight away. It is shown once; FluidTalk stores only a hash of it.

The same tab lists your keys with when each was last used, revokes a key (any agent using it stops working immediately), and can call the live endpoint with a key to check it works.

• A key acts as your whole account. It can create, edit and delete characters and spend tokens from the wallet. Treat it like a password and keep it out of files you commit.
• Only the account owner can create keys. The MCP tab is hidden from team members, so an assistant cannot mint a key that escapes their access.
• Up to 20 active keys per account. Revoke one to make room.
• An MCP key works on /mcp only. It is not a connector token: a production bot on the Characters API authenticates with a per-character ftc_live_... token (see Authentication), which the issue_connector_token tool can create for you.

Connect your client

Every snippet below uses the production endpoint. Replace ftm_your_key_here with your key.

Claude Code

claude mcp add --transport http fluidtalk https://api-talk.fluidvip.com/mcp \
  --header "Authorization: Bearer ftm_your_key_here"

This adds the server for the current project only (Claude Code's default local scope). To use it in every project, add --scope user before the server name. Avoid --scope project with the key written inline: that scope saves to .mcp.json, which is meant to be committed. Check the connection with claude mcp list, or /mcp inside a session.

Cursor

Cursor connects to the HTTP endpoint directly. Add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json in a project root (that project only):

{
  "mcpServers": {
    "fluidtalk": {
      "url": "https://api-talk.fluidvip.com/mcp",
      "headers": {
        "Authorization": "Bearer ftm_your_key_here"
      }
    }
  }
}

To keep the key out of the file, Cursor also accepts an environment variable in a header value: "Authorization": "Bearer ${env:FLUIDTALK_MCP_KEY}".

Claude Desktop

Claude Desktop starts MCP servers as local processes from its config file, so it reaches a remote endpoint like this one through mcp-remote, a small bridge run with npx. It needs Node.js 18 or newer.

1. In Claude Desktop, open Settings → Developer → Edit Config. This opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).
2. Add the server:

{
  "mcpServers": {
    "fluidtalk": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api-talk.fluidvip.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ftm_your_key_here"
      }
    }
  }
}

3. Quit Claude Desktop completely and start it again.

The header value sits in env, with no space after Authorization: in args, on purpose: some clients, Claude Desktop on Windows among them, do not escape spaces inside args, which breaks a Bearer <key> value written there. This is the form mcp-remote documents for that case.

Any other client

Any MCP client that supports the Streamable HTTP transport and a custom request header can connect with the same URL and header. To see the wire format, or to test without a client:

curl -sS https://api-talk.fluidvip.com/mcp \
  -H "Authorization: Bearer ftm_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

Each response is a single JSON body. Notifications (messages without an id) are accepted with 202 and no body.

How an agent uses it

On initialize the server hands the agent a short set of instructions: the order of operations, and everything about a character it is allowed to configure. The typical flow is:

1. whoami — confirm the key works and the wallet has tokens.
2. create_character, or list_templates then clone_template — get a character.
3. bind_platform — required once per platform before the character can chat there.
4. chat — a real, persisted conversation turn. The same handle is the same person: the character remembers them across turns and across platforms. Replies come back as bubbles with delays, to be sent in order.
5. issue_connector_token — when you move from an agent to a production bot on the Characters API.

Persona, voice, knowledge base, photos, platforms, workflows, follow-ups and comment behaviour are all editable through tools; the agent is told to call describe_engine_vocabulary before changing a workflow. update_character replaces any list you send, so read the character first and send the whole list back with your edit applied.

Tools

Area	Tools
Account	whoami
Characters	list_characters, get_character, create_character, update_character, delete_character
Photos	list_photos, add_photo, update_photo, delete_photo, organize_photos, test_photo_selection
Templates	list_templates, clone_template, submit_to_marketplace, unpublish_listing
Workflows	list_engines, describe_engine_vocabulary, get_engine, create_engine, update_engine, validate_engine, delete_engine, define_move, define_card, list_library, save_library_item, delete_library_item, import_card, list_brand_templates, save_brand_template
Platforms	bind_platform, connect_platforms, issue_connector_token
Conversations	chat, list_conversations, get_conversation, sweep_followups, list_followups, ack_followup
Comments	preview_comment, preview_engage, simulate_comment, simulate_comment_reply, list_comment_threads, get_comment_thread
Lookups	search_places, list_countries

Each tool carries MCP annotations (readOnlyHint, destructiveHint), so a client can ask before running anything that deletes.

Billable tools

Seven tools generate text or analyse images, and they spend tokens from the account wallet at your plan's rate, exactly like the Characters API (1 token = $1, billed in small decimals — see Billing & usage):

chat · sweep_followups · organize_photos · preview_comment · preview_engage · simulate_comment · simulate_comment_reply

Every other tool is free. Their descriptions in tools/list end with [Billable: this call spends tokens from the account wallet.]. An agent running in a loop spends real money, so cap how many turns it may take.

Errors

Errors arrive at three levels.

HTTP, before any JSON-RPC is read. Authentication failures return 401 with WWW-Authenticate: Bearer and a detail message:

detail	Cause
Missing MCP key	No Authorization or X-FluidTalk-Key header.
Authorization header must use the Bearer scheme: ...	A key was sent under another scheme.
Invalid or revoked MCP key	The key does not exist or was revoked.

Too many failed attempts from one IP address return 429 with a Retry-After header.

JSON-RPC protocol errors come back as a standard error object: -32700 for a body that is not JSON (HTTP 400), -32600 for a message that is not JSON-RPC 2.0, -32601 for an unknown method, and -32602 when tools/call has no tool name.

Tool errors are a normal result with isError: true and a text message the agent can act on, which is what the MCP specification asks for:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [{ "type": "text", "text": "Invalid arguments: argument 'age' must be at least 18" }],
    "isError": true
  }
}

• Invalid arguments. Every input schema is enforced, including nested fields: required fields, types, enums, minimums and maximums, UUID formats, and unknown fields.
• Refusals from the account. The message ends with the HTTP status the same operation returns in the dashboard, for example (HTTP 402) when the wallet is empty or (HTTP 403) when a plan limit is reached.

A successful call returns the result as JSON text in content, and as structuredContent when the result is an object.