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
Show today’s unanswered chats
3 chats are waiting for a reply:
- MMeera KapoorIs the 2 kg box available?Unassigned42 min
- RRahul MehtaWhere is my order?Riya1 h
- AAsha RaoCan you share the menu?Arjun3 h
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.
https://fliok.com/api/mcpStreamable HTTPTwo ways to sign in
Sign in with Fliok
Claude (claude.ai and Claude Desktop), ChatGPTAdd 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 appA 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_….
| App | Signs in with | How it gets to Fliok |
|---|---|---|
| Claude (claude.ai and Claude Desktop) | Sign in with Fliok | A custom connector, on claude.ai or in the Claude desktop app. |
| 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. |
| Cursor | Fliok API key | Cursor’s MCP settings, with the address and a key. |
| Gemini CLI | Fliok API key | Through Gemini CLI, not the Gemini app. |
| Grok (xAI API) | Fliok API key | Through 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 key | Claude Code, Codex CLI and Gemini CLI, as a remote (HTTP) MCP server with a key. |
| OpenClaw | Fliok API key | Added to its MCP servers. It runs in Telegram and other chat apps. |
| Hermes Agent | Fliok API key | Added to its MCP servers. It runs in Telegram and other chat apps. |
| 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. |
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)
- ChatGPT
- Cursor
- Gemini CLI
- Grok (xAI API)
- Claude Code, Codex CLI and Gemini CLI (commands)
- OpenClaw
- Hermes Agent
- Telegram (through OpenClaw or Hermes)
Claude (claude.ai and Claude Desktop)
Sign in with FliokA custom connector, on claude.ai or in the Claude desktop app.
- 1In Claude, open Settings → Connectors and choose Add custom connector (on Team and Enterprise plans an owner adds it under Organization connectors first).
- 2Name it Fliok and paste https://fliok.com/api/mcp as the remote MCP server URL. Leave the OAuth client fields empty.
- 3Click Connect. Sign in to Fliok, pick the workspace and what Claude may do, and approve (you'll confirm with a code).
- 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 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.
- 1In ChatGPT, open Settings → Apps & Connectors → Advanced settings and switch Developer mode on (Plus, Pro, Business, Enterprise and Edu).
- 2Back in Apps & Connectors choose Create, name it Fliok, paste https://fliok.com/api/mcp as the MCP server URL and choose OAuth.
- 3Sign in to Fliok, pick the workspace and what ChatGPT may do, and approve (you'll confirm with a code).
- 4In a chat, choose Developer mode from the + menu and add Fliok. Search and fetch work in deep research too.
Cursor
Fliok API keyCursor’s MCP settings, with the address and a key.
- 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.
- 2Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project).
- 3Open Cursor Settings → MCP and check that Fliok shows its tools.
{
"mcpServers": {
"fliok": {
"url": "https://fliok.com/api/mcp",
"headers": {
"Authorization": "Bearer ${env:FLIOK_API_KEY}"
}
}
}
}Gemini CLI
Fliok API keyThrough Gemini CLI, not the Gemini app.
- 1Make an API key in Fliok and set it as FLIOK_API_KEY in your shell.
- 2Add this to ~/.gemini/settings.json (or .gemini/settings.json in a project).
- 3Run gemini and type /mcp to see Fliok's tools.
{
"mcpServers": {
"fliok": {
"httpUrl": "https://fliok.com/api/mcp",
"headers": {
"Authorization": "Bearer $FLIOK_API_KEY"
}
}
}
}Grok (xAI API)
Fliok API keyThrough xAI’s API, as a remote MCP tool — for developers building on Grok, not the Grok app.
- 1Make an API key in Fliok for Grok — Read only is the safe start.
- 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.
- 3Put the key in authorization exactly as shown; Fliok accepts it with or without the word Bearer.
{
"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"
}
]
}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.
- 1Make an API key in Fliok and set it as FLIOK_API_KEY in your shell.
- 2Claude Code: run the first command. Codex CLI: add the [mcp_servers.fliok] lines to ~/.codex/config.toml. Gemini CLI: run the last command.
- 3Ask the assistant something like: list my overdue Fliok tasks.
# 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 keyAdded to its MCP servers. It runs in Telegram and other chat apps.
- 1Make an API key in Fliok for OpenClaw and set FLIOK_API_KEY in the environment OpenClaw's gateway runs in.
- 2Add the fliok entry under mcp.servers in ~/.openclaw/openclaw.json, then restart the gateway.
- 3Ask your OpenClaw assistant (in any of its chat apps) about your Fliok inbox.
{
mcp: {
servers: {
fliok: {
url: "https://fliok.com/api/mcp",
transport: "streamable-http",
headers: { Authorization: "Bearer ${FLIOK_API_KEY}" },
},
},
},
}Hermes Agent
Fliok API keyAdded to its MCP servers. It runs in Telegram and other chat apps.
- 1Make an API key in Fliok for Hermes.
- 2Add the fliok entry under mcp_servers in ~/.hermes/config.yaml (replace wa_YOUR_FLIOK_KEY with the key).
- 3Run /reload-mcp in Hermes (or restart it); hermes mcp test fliok checks the connection.
mcp_servers:
fliok:
url: "https://fliok.com/api/mcp"
headers:
Authorization: "Bearer wa_YOUR_FLIOK_KEY"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.
- 1Telegram has no MCP of its own: run OpenClaw or Hermes Agent with its Telegram bot connected, and give it Fliok as above.
- 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.
- 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
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_conversationsList WhatsApp chats | WhatsApp conversations, most recent first, with the contact and when the 24-hour reply window closes. Cursor paging. | conversations:readviewer role or higherGET /conversations | Read-only |
get_conversationGet a chat | One 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 chat | Assign 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 notes | Internal notes on a chat. Never shown to the customer. | conversations:readviewer role or higherGET /conversations/{id}/notes | Read-only |
add_conversation_noteAdd a chat note | Add an internal note to a chat. The customer never sees it. | conversations:writeagent role or higherPOST /conversations/{id}/notes | Changes data |
mark_conversation_readMark a chat read | Mark 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}/read | Sends messages |
Messages 4
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_phone_numbersList WhatsApp numbers | The workspace's WhatsApp numbers with their status and quality. Their id is the phoneNumberId other tools take. | messages:readviewer role or higherGET /phone-numbers | Read-only |
send_messageSend a WhatsApp message | Send 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 /send | Sends messages |
list_messagesList messages | Messages newest first, optionally for one conversation or one delivery status, with cursor paging. | messages:readviewer role or higherGET /messages | Read-only |
start_conversationStart a WhatsApp chat | Start 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 /conversations | Sends messages |
Templates 3
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_templatesList templates | Every WhatsApp template with its language, category, components and Meta approval status. | templates:readviewer role or higherGET /templates | Read-only |
get_templateGet a template | One template with its components, Meta status and any rejection reason. | templates:readviewer role or higherGET /templates/{id} | Read-only |
create_templateCreate a template | Submit a new WhatsApp template to Meta for review (admins). Name: lowercase letters, numbers and underscores. | templates:writeadmin role or higherPOST /templates | Sends messages |
Contacts 10
| Tool | What it does | Needs | Kind |
|---|---|---|---|
searchSearch Fliok | Search 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 /contacts | Read-only |
fetchFetch a record | Fetch 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 contacts | Contacts newest first. search matches any part of a name or number; phone finds one exact number. Cursor paging. | contacts:readviewer role or higherGET /contacts | Read-only |
get_contactGet a contact | One 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 contact | Add a contact by phone number, or update the one that already has it (name, tags, custom fields, opt-in). | contacts:writeagent role or higherPOST /contacts | Changes data |
update_contactUpdate a contact | Change 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 tags | Every tag on the workspace's contacts with how many contacts carry it. | contacts:readviewer role or higherGET /tags | Read-only |
tag_contactsTag contacts | Add and remove tags on up to 500 contacts at once, by id or phone number. | contacts:writeagent role or higherPOST /contacts/bulk-tags | Changes data |
block_contactBlock on WhatsApp | Block a customer on WhatsApp (only within 24 hours of their last message — WhatsApp's rule). | contacts:writeagent role or higherPOST /contacts/{id}/block | Sends messagesCan’t be undone |
unblock_contactUnblock on WhatsApp | Lift a WhatsApp block on a customer. | contacts:writeagent role or higherPOST /contacts/{id}/unblock | Sends messages |
Sales CRM 9
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_leadsList leads | Leads with stage, owner and deal value. Filter by view or q (name, number, email), sort, page through. | crm:readviewer role or higherGET /leads | Read-only |
get_leadGet a lead | One 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 lead | Add a lead by phone number (a known number is updated, never duplicated). Stage and owner by name or email. | crm:writeagent role or higherPOST /leads | Changes data |
update_leadUpdate a lead | Move 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 note | Add a note to a lead's timeline. Never sent to the customer. | crm:writeagent role or higherPOST /leads/{id}/notes | Changes data |
list_tasksList follow-up tasks | Follow-up tasks by status (open, overdue, today, upcoming, done…), assignee, lead or type, with counts. | crm:readviewer role or higherGET /tasks | Read-only |
create_taskCreate a follow-up task | Create 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 /tasks | Changes data |
update_taskUpdate a task | Complete a task (with an outcome), cancel, reschedule or reassign it. | crm:writeagent role or higherPATCH /tasks/{id} | Changes data |
get_pipelineGet the sales pipeline | The pipeline's stages (initial, active, won, lost) and lost reasons. | crm:readviewer role or higherGET /pipeline | Read-only |
Broadcasts 7
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_broadcastsList broadcasts | Recent broadcasts with live sent, delivered and failed counts. | broadcasts:readviewer role or higherGET /broadcasts | Read-only |
get_broadcastGet a broadcast | One broadcast with its delivery progress. | broadcasts:readviewer role or higherGET /broadcasts/{id} | Read-only |
list_broadcast_recipientsList broadcast recipients | Who a broadcast went to and what happened to each (sent, delivered, read, failed and why). Cursor paging. | broadcasts:readviewer role or higherGET /broadcasts/{id}/recipients | Read-only |
preview_broadcastPreview a broadcast | What 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/preview | Read-only |
create_broadcastCreate a broadcast | Send 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 /broadcasts | Sends messagesCan’t be undone |
cancel_broadcastCancel a broadcast | Cancel 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 audiences | Saved audiences (segments) a broadcast can be sent to by segmentId. | broadcasts:readviewer role or higherGET /segments | Read-only |
Invoices and bookings 6
| Tool | What it does | Needs | Kind |
|---|---|---|---|
get_invoiceGet an invoice | One 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 invoice | Save 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-invoices | Sends messages |
list_bookingsList bookings | Bookings: upcoming, past, cancelled or all, by day range, service, status, staff or search. | biz:readviewer role or higherGET /bookings | Read-only |
get_bookingGet a booking | One booking as it stands now. | biz:readviewer role or higherGET /bookings/{id} | Read-only |
create_bookingMake a booking | Book 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 /bookings | Sends messages |
cancel_bookingCancel a booking | Cancel a booking, with an optional reason. The customer is told while it is still ahead. | biz:writeagent role or higherPOST /bookings/{id}/cancel | Sends messagesCan’t be undone |
Instagram 6
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_instagram_conversationsList Instagram chats | Instagram Direct chats with whether the 24-hour reply window is open. Cursor paging. | instagram:readviewer role or higherGET /instagram/conversations | Read-only |
get_instagram_conversationGet an Instagram chat | One Instagram chat and its messages, newest first. | instagram:readviewer role or higherGET /instagram/conversations/{id}/messages | Read-only |
send_instagram_messageReply on Instagram | Reply in an Instagram Direct chat — only within 24 hours of the customer's last message. | instagram:writeagent role or higherPOST /instagram/send | Sends messages |
list_instagram_postsList Instagram posts | Posts written in Fliok: drafts, scheduled, published, failed. | instagram:readviewer role or higherGET /instagram/posts | Read-only |
list_instagram_commentsList Instagram comments | Comments and @mentions on the account's posts — needing a reply, all, mentions or hidden. | instagram:readviewer role or higherGET /instagram/comments | Read-only |
reply_instagram_commentReply to a comment | Reply in public under an Instagram comment. | instagram:writeagent role or higherPOST /instagram/comments/{id}/reply | Sends messages |
WhatsApp Pay 2
| Tool | What it does | Needs | Kind |
|---|---|---|---|
create_payment_requestRequest a payment | Ask for a payment inside a WhatsApp chat (WhatsApp Pay, India; amounts in paise). referenceId makes a retry safe. | payments:writeagent role or higherPOST /payment-requests | Sends messages |
get_payment_requestGet a payment request | Where a payment request stands — by id or your referenceId. | payments:readviewer role or higherGET /payment-requests/{id} | Read-only |
Reports 1
| Tool | What it does | Needs | Kind |
|---|---|---|---|
get_analyticsGet analytics | Message and conversation counts for the last N days (up to 90): sent, delivered, read, failed, inbound. | analytics:readviewer role or higherGET /analytics | Read-only |
Team 2
| Tool | What it does | Needs | Kind |
|---|---|---|---|
get_workspaceWorkspace info | Which Fliok workspace this connection acts in, its plan, and your role there. Call this first. | team:readviewer role or higherGET /me | Read-only |
list_teamList team members | Team members with their user id (for assigning chats, leads and tasks), role and whether they get new chats. | team:readviewer role or higherGET /team | Read-only |
Integrations 1
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_integrationsList integrations | Every connector on the Integrations page and whether it is connected or needs attention. Never a token. | integrations:readviewer role or higherGET /integrations | Read-only |
Webhooks 1
| Tool | What it does | Needs | Kind |
|---|---|---|---|
list_webhooksList webhooks | Registered webhook endpoints and their delivery health (addresses shortened unless you may see them in full). | webhooks:readviewer role or higherGET /webhooks | Read-only |
Plan and wallet (read only) 2
| Tool | What it does | Needs | Kind |
|---|---|---|---|
get_billingGet the plan | The plan in force: trial, renewal, usage against every limit. Nothing about how you pay (admins). | billing:readadmin role or higherGET /billing | Read-only |
get_walletGet the wallet | The usage wallet's balance and what can still be spent (admins). Top-ups happen only in the dashboard. | billing:readadmin role or higherGET /wallet | Read-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 see | What to do |
|---|---|
| 401 Unauthorized, or the app asks you to sign in again | Signed 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_scope | The 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_unavailable | The 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.