floGPT MCP server, CLI and skills

Three front ends over the floGPT public API (/api/v1), sharing one tool catalogue so they cannot drift:

• flogpt-mcp — MCP stdio server, for clients that spawn a local process: Claude Code, Cursor, Codex, VS Code, Claude Desktop, Windsurf, Zed.
• flogpt-mcp-http — MCP Streamable HTTP server, for the clients that cannot: ChatGPT, Claude on the web, Grok, Muse.
• flogpt — the same catalogue as terminal subcommands, so an operator can do by hand exactly what an agent does, and reproduce a failing agent call in one line.

Plus six skills: playbooks for the tasks people actually bring here, served to skill-aware clients as files and to everything else as MCP prompts.

Setup

Create an organization API key in Settings → API Keys, granting only the scopes you want the agent to have. Keys start with fg_live_ or fg_test_.

export FLOGPT_API_KEY=fg_live_...
# Self-hosted or staging:
export FLOGPT_API_URL=https://your-backend.example.com

Connecting a client

The dashboard's Connect an AI assistant panel generates the exact link, command or URL for each client, with your key filled in. npm run generate-install produces the same thing as files (dist/install/).

The short version:

# Claude Code
claude mcp add flogpt --env FLOGPT_API_KEY=fg_live_... -- npx -y @flogpt/mcp

{
  "mcpServers": {
    "flogpt": {
      "command": "npx",
      "args": ["-y", "@flogpt/mcp"],
      "env": { "FLOGPT_API_KEY": "fg_live_..." }
    }
  }
}

Remote clients point at https://api.flogpt.com/mcp with the key as a bearer token.

The two transports have different threat models and it is worth being deliberate. Under stdio the client spawns the process and talks over pipes, so nothing listens on a port and the key never leaves the machine. Over HTTP the key is sent to a server floGPT runs — which stores nothing and acts only under that credential, but the key has left the building. Scope remote keys tighter.

Using the CLI

flogpt help                                  # every command
flogpt whoami                                # which org, which scopes
flogpt call-logs --status failed --limit 20
flogpt call-logs --status failed --table     # human-readable columns
flogpt call-log --callLogId 665f... | jq '.turns'
flogpt tickets --help                        # arguments for one command

Tools

36 tools across discovery, chat and voice agents, calls and transcripts, conversations, knowledge, CRM contacts and tickets, outbound triggers, numbers, data collections, analytics and webhooks — plus flogpt_request as the escape hatch. flogpt help prints the current list; it is generated from the catalogue rather than restated here, because a hand-maintained table in a README is the first thing to go stale.

Why ~36 tools for 126 endpoints

Generating one tool per endpoint is the obvious move and the wrong one: a model handed 126 near-identical tools picks badly, and every tool costs context on every turn. These are the endpoints an agent actually reaches for, described for a model deciding whether to call them. Where the API has many endpoints for one decision, the tool takes the decision as an argument — flogpt_transition_ticket folds in eight ticket endpoints, because the model is choosing a verb, not a route.

Everything else stays reachable:

flogpt request --method GET --path /team

The full endpoint list is at GET /api/v1/openapi.json, also served as the flogpt://openapi MCP resource.

Skills

| Skill | For | | --- | --- | | flogpt-call-triage | Calls are failing and nobody knows why yet | | flogpt-voice-agent-tuning | The agent answers but handles calls badly | | flogpt-outbound-campaign | Setting up and safely launching outbound calling | | flogpt-knowledge-gaps | Agents are hedging on questions they should answer | | flogpt-ticket-triage | Working the CRM ticket queue | | flogpt-workspace-audit | Pre-launch or onboarding health check |

skills/ is the source; npm run bundle-skills emits the per-client layouts into dist/. They are not written into this repo's .cursor/skills/ or .claude/skills/, which hold the developer skills for working on floGPT — a different audience entirely.

Things worth knowing

flogpt_update_call_widget edits the draft. If the agent has a pinned production version, callers keep hearing that version until someone publishes and promotes. The tool description says so, but it is the thing most likely to surprise you.

Three tools make a phone ring. flogpt_test_call_widget, flogpt_fire_outbound_trigger and flogpt_reinitiate_call. They are marked DIALS_A_PHONE in the catalogue, and check-listing fails if one is not disclosed to directory reviewers. Firing a trigger supports dryRun.

A 403 means a missing scope, not a missing permission. The error names the scope; add it in Settings → API Keys. These are different failures with completely different fixes, so they are reported differently.

Rate limits are per key. A 429 means that key's token bucket is empty.

Development

npm install
npm test                  # catalogue conformance, HTTP auth and tenancy, error translation
npm run check-listing     # distribution metadata completeness
npm run build             # skill bundles, install artifacts, submission packets, .mcpb

The catalogue is checked against the backend

test/conformance.test.js reads ORG_API_SCOPES from backend/src/models/OrganizationApiKey.ts and the paths: block of backend/src/api/v1/openapi.yaml, and asserts that every tool's scope is real and every path in its endpoints exists.

This is not ceremony. An earlier version of this catalogue shipped eight invented scopes (call_logs:read, crm_tickets:write, campaigns:read…) and three paths no router serves, and every structural test passed, because "campaigns:read" is a perfectly well-formed string. Roughly a third of the tools could not have worked. When you add a tool, declare its scope and endpoints — they are the only thing standing between this catalogue and plausible fiction.

When the backend is not on disk, those tests skip rather than fail, so npm test is meaningful for someone who installed the published package.

Distribution

distribution/ holds one source for every directory submission; npm run build-submissions renders a packet and runbook per target into dist/submissions/.

Publishing is automated for the channels that have an API — .github/workflows/release-mcp.yml on an mcp-v* tag does npm, the official MCP Registry, the .mcpb and the GitHub release. The four reviewed directories (ChatGPT, Claude, Muse, Cursor) are human-reviewed web forms with no API, so what is automated there is assembling a consistent packet, not submitting it. Grok has no catalogue at all — users add the URL themselves, so its deliverable is a setup page.

Two of those packets are blocked on OAuth Dynamic Client Registration, which floGPT does not support yet. docs/oauth-dcr-design.md is the design; npm run check-listing warns about it until it lands.