Skip to content

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 ​

Endpointhttps://api-talk.fluidvip.com/mcp
TransportStreamable 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 version2025-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.
AuthenticationAuthorization: Bearer ftm_... on every request. X-FluidTalk-Key: ftm_... is accepted for clients that keep Authorization for their own sign-in flow.
Tools51, 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. It stays in the list: show or copy it again any time from the same tab. A key created before keys became viewable appears there after its next use.

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_... 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 ​

bash
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):

json
{
  "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:
json
{
  "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"
      }
    }
  }
}
  1. 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:

bash
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 ​

AreaTools
Accountwhoami, get_usage
Characterslist_characters, get_character, create_character, update_character, delete_character
Photoslist_photos, add_photo, update_photo, delete_photo, organize_photos, test_photo_selection
Templateslist_templates, clone_template, submit_to_marketplace, unpublish_listing
Workflowslist_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
Platformsbind_platform, connect_platforms, issue_connector_token
Conversationschat, list_conversations, get_conversation, sweep_followups, list_followups, ack_followup
Commentspreview_comment, preview_engage, simulate_comment, simulate_comment_reply, list_comment_threads, get_comment_thread
Postslist_posts, get_post
Lookupssearch_places, list_countries

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

Reading history ​

list_comment_threads and list_posts return the newest rows first. To page back, pass the created_at of the last row you already have as before; you get the rows strictly older than it. A before that is not an ISO-8601 timestamp is a tool error.

list_posts includes refusals (decision no_suitable_post_found or generation_failed) as well as posts, and rows with mode preview are kept Post Tester runs. Conversations, comment threads and each comment carry an origin: api for live connector traffic, sim for the dashboard or MCP simulator, test for the v1 sandbox. A thread's origin says who opened it and a comment's says who wrote it, since a simulated reply can be added to a live thread. list_conversations and list_comment_threads take an origin filter; rows written before origin was recorded have none and match no filter.

Conversations, comment threads and each of her comments also carry cost_usd, what they have cost you at your plan's price (null = not recorded). get_usage (free; optional since and character_id) sums the cost recorded on conversations, her comments and posts by kind, origin and character, and counts items with no recorded cost in not_recorded rather than as $0: conversations and comments record cost from 2026-10-06. Posts are grouped by mode, so a live post counts as api and a kept Post Tester run as sim. Previews, the photo organiser, the embedding behind a test_photo_selection text query and rekindle follow-ups are billed with no item to attach them to, so they are not in these totals.

Workflows that never sell ​

validate_engine, create_engine and update_engine warn with NO_PITCH_CARD when no reachable phase holds a LINK_DROP, CROSSOVER or SELL card, because such a workflow can talk but never sell. If that is on purpose (a workflow for public discussion only), set no_funnel: true at the top level of the workflow's config; the same finding is then reported as info. Without the flag it stays a warning, including when comments.drive_to_dm is off: that setting only stops comments from pushing readers to DMs, and the workflow may still sell there.

Comment length ​

preview_comment, preview_engage, simulate_comment and simulate_comment_reply take an optional integer max_chars (20 to 2200): the longest comment or reply for that one call. To change it for every call, set max_comment_chars in the workflow's comments block (config.comments on create_engine / update_engine); null or 0 keeps the default of 150 characters (every platform; until 2026-10-12 it was set per platform: Instagram 220, X 280, Reddit 500), and validate_engine reports a value outside 20 to 2200 as an error. max_chars wins over the setting, and neither goes above the platform's own ceiling. Every result with generated text carries max_chars, the limit applied, and truncated, whether it had to be shortened and reads as unfinished. The ceilings per platform are in the Comments guide.

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, apart from the embedding test_photo_selection runs for a text query, which is billed at cost like any other model call. The seven tools' 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:

detailCause
Missing MCP keyNo Authorization or X-FluidTalk-Key header.
Authorization header must use the Bearer scheme: ...A key was sent under another scheme.
Invalid or revoked MCP keyThe 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:

json
{
  "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.

FluidTalk Characters API — part of the Fluidvip ecosystem.