Skip to content

MCP — Documentation

Use Fliok from your AI apps

Fliok runs an MCP server, so Claude, ChatGPT, Cursor, Gemini CLI and other AI apps can read your chats, send approved templates and add leads — with the permissions you approve, and nothing more.

Server addresshttps://fliok.com/api/mcp

60
Tools
2
Ways to sign in
Pro
Plan and above, like the API
HTTP
Streamable HTTP transport

What MCP is

The Model Context Protocol (MCP) is an open standard that lets an AI app use tools from other services. Fliok runs an MCP server: connect it to the AI app you already use, and you can ask that app in plain words — “show today’s unanswered chats”, “send the order-update template to this customer”, “create a lead from this email” — and it does the work through Fliok’s tools, with your workspace’s permissions. Each tool maps to an endpoint of Fliok’s REST API, with the same rules, limits and records.

AI apps connect on Pro and Enterprise, the plans with the REST API. Fliok’s own AI agent, which answers your customers, is separate and works without any of this.

The server address

One address for every app. It speaks MCP’s Streamable HTTP transport, so apps that add a remote MCP server by its URL can use it directly.

MCP serverhttps://fliok.com/api/mcp
TransportStreamable HTTP
Sign-inSign in with Fliok, or a Fliok API key

Two ways to sign in

Sign in with Fliok

Claude (claude.ai and Claude Desktop), ChatGPT

Add Fliok as a custom connector: paste the address, sign in to Fliok, and approve what the app may do. Nothing to copy and keep safe.

A Fliok API key

Every other app

A workspace admin creates a key (it starts wa_) on the API keys page and narrows it to the scopes the app needs. The app sends it as Authorization: Bearer wa_….

AppSigns in withHow it gets to Fliok
Claude (claude.ai and Claude Desktop)Sign in with FliokA custom connector, on claude.ai or in the Claude desktop app.
ChatGPTSign in with FliokA custom connector. Needs ChatGPT’s developer mode, which is offered on some ChatGPT plans only; actions that change things may depend on the ChatGPT plan.
CursorFliok API keyCursor’s MCP settings, with the address and a key.
Gemini CLIFliok API keyThrough Gemini CLI, not the Gemini app.
Grok (xAI API)Fliok API keyThrough xAI’s API, as a remote MCP tool — for developers building on Grok, not the Grok app.
Claude Code, Codex CLI and Gemini CLI (commands)Fliok API keyClaude Code, Codex CLI and Gemini CLI, as a remote (HTTP) MCP server with a key.
OpenClawFliok API keyAdded to its MCP servers. It runs in Telegram and other chat apps.
Hermes AgentFliok API keyAdded to its MCP servers. It runs in Telegram and other chat apps.
Telegram (through OpenClaw or Hermes)Fliok API keyThrough an AI agent that runs in Telegram, such as OpenClaw or Hermes. Fliok has no Telegram bot.

ChatGPT’s custom connectors need its developer mode, which is offered on some ChatGPT plans only, and whether ChatGPT may carry out actions that change things can depend on your ChatGPT plan. That is ChatGPT’s setting; Fliok can’t change it.

Set up your app

The steps for each app: 2 sign in with Fliok, 7 use a Fliok API key. Pick yours.

Claude (claude.ai and Claude Desktop)

Sign in with Fliok

A custom connector, on claude.ai or in the Claude desktop app.

  1. 1In Claude, open Settings → Connectors and choose Add custom connector (on Team and Enterprise plans an owner adds it under Organization connectors first).
  2. 2Name it Fliok and paste https://fliok.com/api/mcp as the remote MCP server URL. Leave the OAuth client fields empty.
  3. 3Click Connect. Sign in to Fliok, pick the workspace and what Claude may do, and approve (you'll confirm with a code).
  4. 4In a chat, open the tools menu and switch the Fliok tools on. Claude asks before it sends anything.

What Claude (claude.ai and Claude Desktop) can do with Fliok

ChatGPT

Sign in with Fliok

A custom connector. Needs ChatGPT’s developer mode, which is offered on some ChatGPT plans only; actions that change things may depend on the ChatGPT plan.

  1. 1In ChatGPT, open Settings → Apps & Connectors → Advanced settings and switch Developer mode on (Plus, Pro, Business, Enterprise and Edu).
  2. 2Back in Apps & Connectors choose Create, name it Fliok, paste https://fliok.com/api/mcp as the MCP server URL and choose OAuth.
  3. 3Sign in to Fliok, pick the workspace and what ChatGPT may do, and approve (you'll confirm with a code).
  4. 4In a chat, choose Developer mode from the + menu and add Fliok. Search and fetch work in deep research too.

What ChatGPT can do with Fliok

Cursor

Fliok API key

Cursor’s MCP settings, with the address and a key.

  1. 1Make an API key for Cursor in Fliok (Settings → Integrations → AI apps → Create a key) and set it as FLIOK_API_KEY in your shell.
  2. 2Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project).
  3. 3Open Cursor Settings → MCP and check that Fliok shows its tools.
json
{
  "mcpServers": {
    "fliok": {
      "url": "https://fliok.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FLIOK_API_KEY}"
      }
    }
  }
}

What Cursor can do with Fliok

Gemini CLI

Fliok API key

Through Gemini CLI, not the Gemini app.

  1. 1Make an API key in Fliok and set it as FLIOK_API_KEY in your shell.
  2. 2Add this to ~/.gemini/settings.json (or .gemini/settings.json in a project).
  3. 3Run gemini and type /mcp to see Fliok's tools.
json
{
  "mcpServers": {
    "fliok": {
      "httpUrl": "https://fliok.com/api/mcp",
      "headers": {
        "Authorization": "Bearer $FLIOK_API_KEY"
      }
    }
  }
}

What Gemini CLI can do with Fliok

Grok (xAI API)

Fliok API key

Through xAI’s API, as a remote MCP tool — for developers building on Grok, not the Grok app.

  1. 1Make an API key in Fliok for Grok — Read only is the safe start.
  2. 2Pass Fliok as a remote MCP tool in your xAI API request (the Responses API at https://api.x.ai/v1/responses, or mcp(...) in the xai-sdk). Grok calls Fliok's tools from xAI's servers.
  3. 3Put the key in authorization exactly as shown; Fliok accepts it with or without the word Bearer.
json
{
  "model": "YOUR_GROK_MODEL",
  "input": [
    {
      "role": "user",
      "content": "Which WhatsApp chats in Fliok are waiting for a reply?"
    }
  ],
  "tools": [
    {
      "type": "mcp",
      "server_url": "https://fliok.com/api/mcp",
      "server_label": "fliok",
      "authorization": "wa_YOUR_FLIOK_KEY"
    }
  ]
}

What Grok (xAI API) can do with Fliok

Claude Code, Codex CLI and Gemini CLI (commands)

Fliok API key

Claude Code, Codex CLI and Gemini CLI, as a remote (HTTP) MCP server with a key.

  1. 1Make an API key in Fliok and set it as FLIOK_API_KEY in your shell.
  2. 2Claude Code: run the first command. Codex CLI: add the [mcp_servers.fliok] lines to ~/.codex/config.toml. Gemini CLI: run the last command.
  3. 3Ask the assistant something like: list my overdue Fliok tasks.
bash
# Claude Code
claude mcp add --transport http fliok https://fliok.com/api/mcp --header "Authorization: Bearer $FLIOK_API_KEY"

# Codex CLI — ~/.codex/config.toml
# [mcp_servers.fliok]
# url = "https://fliok.com/api/mcp"
# bearer_token_env_var = "FLIOK_API_KEY"

# Gemini CLI
gemini mcp add --transport http fliok https://fliok.com/api/mcp --header "Authorization: Bearer $FLIOK_API_KEY"

What Claude Code, Codex CLI and Gemini CLI (commands) can do with Fliok

OpenClaw

Fliok API key

Added to its MCP servers. It runs in Telegram and other chat apps.

  1. 1Make an API key in Fliok for OpenClaw and set FLIOK_API_KEY in the environment OpenClaw's gateway runs in.
  2. 2Add the fliok entry under mcp.servers in ~/.openclaw/openclaw.json, then restart the gateway.
  3. 3Ask your OpenClaw assistant (in any of its chat apps) about your Fliok inbox.
json5
{
  mcp: {
    servers: {
      fliok: {
        url: "https://fliok.com/api/mcp",
        transport: "streamable-http",
        headers: { Authorization: "Bearer ${FLIOK_API_KEY}" },
      },
    },
  },
}

What OpenClaw can do with Fliok

Hermes Agent

Fliok API key

Added to its MCP servers. It runs in Telegram and other chat apps.

  1. 1Make an API key in Fliok for Hermes.
  2. 2Add the fliok entry under mcp_servers in ~/.hermes/config.yaml (replace wa_YOUR_FLIOK_KEY with the key).
  3. 3Run /reload-mcp in Hermes (or restart it); hermes mcp test fliok checks the connection.
yaml
mcp_servers:
  fliok:
    url: "https://fliok.com/api/mcp"
    headers:
      Authorization: "Bearer wa_YOUR_FLIOK_KEY"

What Hermes Agent can do with Fliok

Telegram (through OpenClaw or Hermes)

Fliok API key

Through an AI agent that runs in Telegram, such as OpenClaw or Hermes. Fliok has no Telegram bot.

  1. 1Telegram has no MCP of its own: run OpenClaw or Hermes Agent with its Telegram bot connected, and give it Fliok as above.
  2. 2Lock the bot to your own Telegram account (OpenClaw's pairing or allow-list, Hermes's allowed users). Anyone who can message the bot can use Fliok with your key.
  3. 3Use a narrow key — Read only, or Read + reply — and message your bot: "Any new leads in Fliok today?"

What Telegram (through OpenClaw or Hermes) can do with Fliok

Tools

Every tool the server offers, by area, with the scope it needs and the lowest role that can use it. An app sees only the tools its key’s scopes, or what you approved, allow. Each tool calls the API endpoint named under it.

  • Read-only looks things up and changes nothing
  • Changes data changes something in Fliok
  • Sends messages reaches a customer
  • Can’t be undone

Chats 6

ToolWhat it doesNeedsKind
list_conversationsList WhatsApp chatsWhatsApp conversations, most recent first, with the contact and when the 24-hour reply window closes. Cursor paging.conversations:readviewer role or higherGET /conversationsRead-only
get_conversationGet a chatOne conversation: state, priority, assignee, the contact, and whether a free-form reply is possible right now.conversations:readviewer role or higherGET /conversations/{id}Read-only
update_conversationUpdate a chatAssign a chat to a team member (or unassign), set its priority, resolve, reopen or archive it.conversations:writeagent role or higherPATCH /conversations/{id}Changes data
list_conversation_notesList chat notesInternal notes on a chat. Never shown to the customer.conversations:readviewer role or higherGET /conversations/{id}/notesRead-only
add_conversation_noteAdd a chat noteAdd an internal note to a chat. The customer never sees it.conversations:writeagent role or higherPOST /conversations/{id}/notesChanges data
mark_conversation_readMark a chat readMark a chat read, as opening it in the inbox does: unread goes to 0 and the customer sees blue ticks.conversations:writeagent role or higherPOST /conversations/{id}/readSends messages

Messages 4

ToolWhat it doesNeedsKind
list_phone_numbersList WhatsApp numbersThe workspace's WhatsApp numbers with their status and quality. Their id is the phoneNumberId other tools take.messages:readviewer role or higherGET /phone-numbersRead-only
send_messageSend a WhatsApp messageSend a WhatsApp message to one person: type text (only inside the 24-hour window after their last message) or template (an approved template, any time), or media/interactive. `to` is the phone number in international format. Goes through every send safety check.messages:sendagent role or higherPOST /sendSends messages
list_messagesList messagesMessages newest first, optionally for one conversation or one delivery status, with cursor paging.messages:readviewer role or higherGET /messagesRead-only
start_conversationStart a WhatsApp chatStart a chat with one person — by contactId or number — with an approved template. With lookup: true it only finds the existing chat and sends nothing.messages:sendagent role or higherPOST /conversationsSends messages

Templates 3

ToolWhat it doesNeedsKind
list_templatesList templatesEvery WhatsApp template with its language, category, components and Meta approval status.templates:readviewer role or higherGET /templatesRead-only
get_templateGet a templateOne template with its components, Meta status and any rejection reason.templates:readviewer role or higherGET /templates/{id}Read-only
create_templateCreate a templateSubmit a new WhatsApp template to Meta for review (admins). Name: lowercase letters, numbers and underscores.templates:writeadmin role or higherPOST /templatesSends messages

Contacts 10

ToolWhat it doesNeedsKind
searchSearch FliokSearch the workspace by text — contacts, leads, templates and broadcasts whose name, number or email matches. Returns ids like contact:<uuid> to pass to fetch.contacts:readviewer role or higherGET /contactsRead-only
fetchFetch a recordFetch one record by the id search returned: contact:<id>, lead:<id>, conversation:<id>, message:<id>, template:<id>, broadcast:<id>, booking:<id>, invoice:<id> or payment:<id>.contacts:readviewer role or higherGET /contacts/{id}Read-only
list_contactsList contactsContacts newest first. search matches any part of a name or number; phone finds one exact number. Cursor paging.contacts:readviewer role or higherGET /contactsRead-only
get_contactGet a contactOne contact with tags, custom fields and opt-in status — by id or phone number.contacts:readviewer role or higherGET /contacts/{id}Read-only
upsert_contactAdd or update a contactAdd a contact by phone number, or update the one that already has it (name, tags, custom fields, opt-in).contacts:writeagent role or higherPOST /contactsChanges data
update_contactUpdate a contactChange a contact's name, tags (replaces the list), custom fields (merged) or opt-in status.contacts:writeagent role or higherPATCH /contacts/{id}Changes data
list_tagsList tagsEvery tag on the workspace's contacts with how many contacts carry it.contacts:readviewer role or higherGET /tagsRead-only
tag_contactsTag contactsAdd and remove tags on up to 500 contacts at once, by id or phone number.contacts:writeagent role or higherPOST /contacts/bulk-tagsChanges data
block_contactBlock on WhatsAppBlock a customer on WhatsApp (only within 24 hours of their last message — WhatsApp's rule).contacts:writeagent role or higherPOST /contacts/{id}/blockSends messagesCan’t be undone
unblock_contactUnblock on WhatsAppLift a WhatsApp block on a customer.contacts:writeagent role or higherPOST /contacts/{id}/unblockSends messages

Sales CRM 9

ToolWhat it doesNeedsKind
list_leadsList leadsLeads with stage, owner and deal value. Filter by view or q (name, number, email), sort, page through.crm:readviewer role or higherGET /leadsRead-only
get_leadGet a leadOne lead with stage, owner, rating, deal value and custom fields — by id or phone number.crm:readviewer role or higherGET /leads/{id}Read-only
create_leadAdd a leadAdd a lead by phone number (a known number is updated, never duplicated). Stage and owner by name or email.crm:writeagent role or higherPOST /leadsChanges data
update_leadUpdate a leadMove a lead's stage (with a lost reason), reassign it, rate it, tag it or edit its fields.crm:writeagent role or higherPATCH /leads/{id}Changes data
add_lead_noteAdd a lead noteAdd a note to a lead's timeline. Never sent to the customer.crm:writeagent role or higherPOST /leads/{id}/notesChanges data
list_tasksList follow-up tasksFollow-up tasks by status (open, overdue, today, upcoming, done…), assignee, lead or type, with counts.crm:readviewer role or higherGET /tasksRead-only
create_taskCreate a follow-up taskCreate a follow-up (call, meeting, to-do) on a lead, due at a time; assigned to the lead's owner unless you say.crm:writeagent role or higherPOST /tasksChanges data
update_taskUpdate a taskComplete a task (with an outcome), cancel, reschedule or reassign it.crm:writeagent role or higherPATCH /tasks/{id}Changes data
get_pipelineGet the sales pipelineThe pipeline's stages (initial, active, won, lost) and lost reasons.crm:readviewer role or higherGET /pipelineRead-only

Broadcasts 7

ToolWhat it doesNeedsKind
list_broadcastsList broadcastsRecent broadcasts with live sent, delivered and failed counts.broadcasts:readviewer role or higherGET /broadcastsRead-only
get_broadcastGet a broadcastOne broadcast with its delivery progress.broadcasts:readviewer role or higherGET /broadcasts/{id}Read-only
list_broadcast_recipientsList broadcast recipientsWho a broadcast went to and what happened to each (sent, delivered, read, failed and why). Cursor paging.broadcasts:readviewer role or higherGET /broadcasts/{id}/recipientsRead-only
preview_broadcastPreview a broadcastWhat create_broadcast would do with this audience — how many match, will send, are suppressed and why, and Meta's estimated cost. Sends and saves nothing (admins).broadcasts:writeadmin role or higherPOST /broadcasts/previewRead-only
create_broadcastCreate a broadcastSend an approved template to an audience (tags, contact ids or a saved segment), now or scheduled (admins). Messages cannot be recalled once sent — preview first.broadcasts:writeadmin role or higherPOST /broadcastsSends messagesCan’t be undone
cancel_broadcastCancel a broadcastCancel a scheduled or sending broadcast. Messages already handed to WhatsApp are not recalled.broadcasts:writeadmin role or higherDELETE /broadcasts/{id}Changes dataCan’t be undone
list_segmentsList saved audiencesSaved audiences (segments) a broadcast can be sent to by segmentId.broadcasts:readviewer role or higherGET /segmentsRead-only

Invoices and bookings 6

ToolWhat it doesNeedsKind
get_invoiceGet an invoiceOne invoice, proforma or quotation your business issued (drafts too): status, totals, received and balance (admins).biz:readadmin role or higherGET /sales-invoices/{id}Read-only
create_invoiceCreate an invoiceSave a draft invoice, proforma or quotation — or issue it and send it to the customer in one step (admins). Amounts in minor units (paise).biz:writeadmin role or higherPOST /sales-invoicesSends messages
list_bookingsList bookingsBookings: upcoming, past, cancelled or all, by day range, service, status, staff or search.biz:readviewer role or higherGET /bookingsRead-only
get_bookingGet a bookingOne booking as it stands now.biz:readviewer role or higherGET /bookings/{id}Read-only
create_bookingMake a bookingBook a service for a contact or a new customer, with the same availability and deposit rules as the dashboard. The customer is told.biz:writeagent role or higherPOST /bookingsSends messages
cancel_bookingCancel a bookingCancel a booking, with an optional reason. The customer is told while it is still ahead.biz:writeagent role or higherPOST /bookings/{id}/cancelSends messagesCan’t be undone

Instagram 6

ToolWhat it doesNeedsKind
list_instagram_conversationsList Instagram chatsInstagram Direct chats with whether the 24-hour reply window is open. Cursor paging.instagram:readviewer role or higherGET /instagram/conversationsRead-only
get_instagram_conversationGet an Instagram chatOne Instagram chat and its messages, newest first.instagram:readviewer role or higherGET /instagram/conversations/{id}/messagesRead-only
send_instagram_messageReply on InstagramReply in an Instagram Direct chat — only within 24 hours of the customer's last message.instagram:writeagent role or higherPOST /instagram/sendSends messages
list_instagram_postsList Instagram postsPosts written in Fliok: drafts, scheduled, published, failed.instagram:readviewer role or higherGET /instagram/postsRead-only
list_instagram_commentsList Instagram commentsComments and @mentions on the account's posts — needing a reply, all, mentions or hidden.instagram:readviewer role or higherGET /instagram/commentsRead-only
reply_instagram_commentReply to a commentReply in public under an Instagram comment.instagram:writeagent role or higherPOST /instagram/comments/{id}/replySends messages

WhatsApp Pay 2

ToolWhat it doesNeedsKind
create_payment_requestRequest a paymentAsk for a payment inside a WhatsApp chat (WhatsApp Pay, India; amounts in paise). referenceId makes a retry safe.payments:writeagent role or higherPOST /payment-requestsSends messages
get_payment_requestGet a payment requestWhere a payment request stands — by id or your referenceId.payments:readviewer role or higherGET /payment-requests/{id}Read-only

Reports 1

ToolWhat it doesNeedsKind
get_analyticsGet analyticsMessage and conversation counts for the last N days (up to 90): sent, delivered, read, failed, inbound.analytics:readviewer role or higherGET /analyticsRead-only

Team 2

ToolWhat it doesNeedsKind
get_workspaceWorkspace infoWhich Fliok workspace this connection acts in, its plan, and your role there. Call this first.team:readviewer role or higherGET /meRead-only
list_teamList team membersTeam members with their user id (for assigning chats, leads and tasks), role and whether they get new chats.team:readviewer role or higherGET /teamRead-only

Integrations 1

ToolWhat it doesNeedsKind
list_integrationsList integrationsEvery connector on the Integrations page and whether it is connected or needs attention. Never a token.integrations:readviewer role or higherGET /integrationsRead-only

Webhooks 1

ToolWhat it doesNeedsKind
list_webhooksList webhooksRegistered webhook endpoints and their delivery health (addresses shortened unless you may see them in full).webhooks:readviewer role or higherGET /webhooksRead-only

Plan and wallet (read only) 2

ToolWhat it doesNeedsKind
get_billingGet the planThe plan in force: trial, renewal, usage against every limit. Nothing about how you pay (admins).billing:readadmin role or higherGET /billingRead-only
get_walletGet the walletThe usage wallet's balance and what can still be spent (admins). Top-ups happen only in the dashboard.billing:readadmin role or higherGET /walletRead-only

Security and revoking

  • The same rules as the API. Everything the AI app does goes through the same permissions, plan limits, staff restrictions and audit trail as Fliok’s API.
  • You decide what it may do. Signing in with Fliok, you see what the app asks to do and approve it. With a key, a workspace admin picks its scopes, and a key never gets more than its role allows.
  • Money stays in the dashboard. No money moves through it: it cannot buy a plan, top up the wallet or change how you pay.
  • Revoke at any time. In Settings → Integrations → AI apps. A key can also be revoked on the API keys page.
  • Ordinary WhatsApp messages. What it sends goes from your number with the inbox’s checks: free-form text only inside the 24-hour window, no message to a customer who opted out, and Meta’s charges as usual.
  • Give it only what it needs. What the AI app reads through Fliok is handled under that app’s own terms. Keep keys out of shared code and chats.

Troubleshooting

What you seeWhat to do
401 Unauthorized, or the app asks you to sign in againSigned in with Fliok: remove the connection in the app and connect again. With a key: the key was revoked, has expired or was copied wrong — create a new one and put it in the app.
A tool you expected is missing, or refused with insufficient_scopeThe app sees only what its key’s scopes — or what you approved — allow. Give the key the scope the tool list names, or connect again and approve it. A key never gets more than its role allows.
402 plan_feature_unavailableThe workspace is not on Pro and Enterprise. AI apps connect on the same plans as the REST API.
A send is refused (outside_24h_window, contact_opted_out, a plan limit)The same rules as the inbox and the API: free-form text needs the customer’s open 24-hour window (send an approved template instead), an opted-out customer is not messaged, and the month’s allowance is the plan’s. The answer names the reason; the error codes explain each one.

More

Connect your first AI app

On Pro and Enterprise. Connect it in Settings, and revoke it there at any time.