Docs/API & MCP/MCP Server

MCP Server

Connect Claude Code, Cursor, and other MCP clients to Flowback

Flowback ships a hosted Model Context Protocol server so AI agents like Claude Code, Claude Desktop, Cursor, and Codex can read and update your workspace directly. Connect once with a workspace-scoped API key and your assistant can browse channels, triage submissions, and update issue priority and status without leaving the editor.

Endpoint

The MCP server is hosted at:

https://mcp.flowback.co/mcp

It speaks the standard Streamable HTTP transport, so any MCP-compatible client that supports HTTP transport with a Bearer token will work.

Authentication

Every request authenticates with an API key passed in the Authorization header:

Authorization: Bearer fb_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create keys from the API & MCP page in your dashboard. The full plaintext key is displayed once at creation and cannot be recovered afterwards — store it somewhere safe before closing the dialog.

Warning

API keys grant full access to the scopes you select for the entire workspace. Treat them like passwords: never commit them to source control, and revoke any key you suspect has been exposed.

Scopes

Each key carries a fixed set of scopes that gate what tools the agent can call. When creating a key you choose one of two presets:

Preset	Scopes	Use case
Read-only	issues:read, submissions:read, channels:read, statuses:read, comments:read	Browsing, triage assistants, dashboards, read-only research agents
Read + write	All read scopes plus issues:write	Agents that update issue priority, title, description, or status

Note

Write scope today only covers issue priority, title, description, and status. Tools cannot create issues, delete data, or modify workspace settings.

Connecting clients

Substitute your plaintext key for fb_sk_… in each example below.

Claude Code

From any terminal:

claude mcp add --transport http --scope user flowback \
  https://mcp.flowback.co/mcp \
  --header "Authorization: Bearer fb_sk_…"

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flowback": {
      "transport": "http",
      "url": "https://mcp.flowback.co/mcp",
      "headers": {
        "Authorization": "Bearer fb_sk_…"
      }
    }
  }
}

Cursor

Open Settings → MCP and add a new server with HTTP transport, the URL https://mcp.flowback.co/mcp, and an Authorization header set to Bearer fb_sk_….

Codex

Codex supports HTTP transport with Bearer headers — point it at https://mcp.flowback.co/mcp with the same Authorization: Bearer fb_sk_… header used everywhere else.

Available tools

The server exposes eight tools. Read tools require the :read scope for the resource; write tools require the matching :write scope.

Tool	Scope	What it does
list_issues	issues:read	Filter issues by status, priority, channel, assignee, labels, search, and date. Paginated.
get_issue	issues:read	Fetch a single issue with comments, linked submissions, and sync events. Accepts a UUID, native reference (FB-123), or external URL.
update_issue	issues:write	Update priority, title, or description on an existing issue.
update_issue_status	issues:write	Move an issue to a different workspace status (by name or status UUID).
list_submissions	submissions:read	Filter submissions by channel, category, submitter, date, search, or whether they have a linked issue. Paginated.
get_submission	submissions:read	Fetch a submission with metadata, conversation, generated PRD, and attachment URLs.
list_channels	channels:read	List feedback intake channels, optionally filtered by status (active, paused) or type (internal, external).
list_statuses	statuses:read	List every status configured for the workspace. Useful for resolving status names before update_issue_status.

Rate limits

The MCP server enforces three independent rate limits per request. The first limit hit is the one returned, and a Retry-After header tells your client when to try again.

Limit	Starter	Pro
Workspace requests / minute	60	1,000
Workspace requests / day	5,000	200,000
Per-key requests / minute	30	500

Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers reflecting the workspace per-minute bucket. Limits exceeded responses return HTTP 429.

Errors

Errors follow the MCP JSON-RPC spec. The most common ones you'll see:

Missing or invalid API key — the bearer token is absent, malformed, or has been revoked. Create a fresh key from the dashboard.
Insufficient scope — the tool requires a scope this key doesn't carry. Recreate the key with the read + write preset (or revoke and replace it) to gain write access.
Rate limit exceeded — back off until the Retry-After window passes. If you hit the daily ceiling regularly, consider upgrading your plan or batching agent activity.
Issue not found — double-check the identifier you're passing. Native references look like FB-123; UUIDs and full external URLs are also accepted.

Auditing and revocation

Every MCP request is logged with the calling key, the tool invoked, the outcome, and latency. The API & MCP page shows each key's last-used timestamp and lets you revoke a key instantly — revoked keys stop working on the very next request.

Tip

Create a separate key per agent or environment (e.g. one for Claude Code on your laptop, another for a CI bot). That way you can rotate or revoke a single integration without disrupting the others.

Versioning

This is the v1 server. Tools, scopes, and rate limits documented here are stable. New tools and scopes will be added in a backward- compatible way; breaking changes will get a separate endpoint version.

Slack

Dashboard & Analytics