Flick Docs

API and MCP Integrations

Connect Flick's workspace-scoped API and read-only MCP server to Claude Code, Codex, Claude.ai, ChatGPT.com, and other remote MCP clients.

Last verified: July 2, 2026.

Endpoints

Surface URL Purpose
Agent onboarding https://joinflick.co/mcp Public funnel for Claude Code, Codex, Claude.ai, Claude Desktop, and ChatGPT setup.
Direct API origin https://api.joinflick.co/api/* Workspace-authenticated JSON API routes.
Browser API path https://joinflick.co/api/* Same API, proxied from the public web app.
MCP server https://api.joinflick.co/mcp Remote MCP JSON-RPC endpoint for AI clients.
MCP resource metadata https://api.joinflick.co/.well-known/oauth-protected-resource/mcp Protected-resource metadata for remote MCP clients. Root alias: /.well-known/oauth-protected-resource.

Local and non-production environments expose FastAPI's generated OpenAPI UI at /api/docs, /api/redoc, and /api/openapi.json. Production disables those generated docs.

API Surface

Flick's production API uses Clerk-authenticated organizations, tenant mapping, explicit workspace scope, and fail-closed authorization. API callers send Authorization: Bearer <token>; the token must resolve to an active organization and workspace before tenant-owned data is read or mutated.

Account Research

Read accounts, drawer snapshots, account context, source tracking, signal monitors, source gaps, and research runs.

/api/accounts, /api/accounts/{company_id}/research

People Search

Launch people searches, review candidates, enrich possible people, and map approved people to role lanes.

/api/accounts/{company_id}/people-searches

Plays

List Plays, orchestrate drafts, add manual Plays, confirm annotations, and execute provider actions only after user confirmation.

/api/plays, /api/plays/orchestrate

Browser-facing API responses are safe projections: account IDs and names, source titles and URLs, snippets, retrieved dates, signal summaries, reviewed people, candidate review state, Play state, readiness states, and billing projections. They must not include raw provider bodies, raw CRM payloads, request headers, secrets, token values, encrypted credentials, or cross-tenant data.

MCP Server

Flick's public MCP server exposes persisted research findings, account briefs, leads, and Play context that Flick already compiled for the authenticated workspace. It does not run providers, compile graph state on demand, create Play drafts, mutate motion specs, or expose raw evidence payloads. The one write tool, flick_add_manual_leads, adds leads by LinkedIn profile URL and sits behind the explicit flick.leads.write scope.

OAuth clients discover sign-in from the protected-resource metadata and the WWW-Authenticate challenge on unauthenticated /mcp requests. OAuth sign-in uses openid profile email public_metadata user:org:read. Headless agents use a workspace agent API key created under Settings then Agents in Flick, sent as Authorization: Bearer fk_... to /mcp or the JSON API. Keys carry the stricter flick.* tool scopes below.

Tool OAuth scope Bearer-token scope What it returns
flick_get_workspace_status user:org:read flick.context.read Workspace id, read-only status, tool count, and cache status.
flick_list_accounts user:org:read flick.context.read Accounts with persisted safe signal projections.
flick_list_research_findings user:org:read flick.context.read Claim-backed research findings for one account with evidence citations.
flick_get_account_brief user:org:read flick.context.read The persisted account brief with source-backed recommendations.
flick_list_manual_leads user:org:read flick.people.read Manually added leads with collection status and remaining capacity.
flick_list_plays user:org:read flick.plays.read Persisted Play decisions and annotations.
flick_add_manual_leads not granted by OAuth read scope flick.leads.write Adds leads by LinkedIn profile URL. Spends workspace credits. 
curl -s https://api.joinflick.co/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FLICK_MCP_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

How To Connect

Claude Code

claude mcp add --transport http flick https://api.joinflick.co/mcp
claude mcp login flick
claude mcp list

For bearer-token setups, add the server with an authorization header or use environment-variable expansion in Claude Code's MCP config.

Codex

codex mcp add flick --url https://api.joinflick.co/mcp
codex mcp login flick
codex mcp list
[mcp_servers.flick]
url = "https://api.joinflick.co/mcp"
bearer_token_env_var = "FLICK_MCP_TOKEN"

Claude.ai

  1. Open claude.ai.
  2. Go to Customize -> Connectors.
  3. Click +, choose Add custom connector, and name it Flick.
  4. Use https://api.joinflick.co/mcp as the connector URL.
  5. Complete authorization and review the requested scopes.

ChatGPT.com

  1. Use a ChatGPT workspace where custom MCP apps are available.
  2. Have an admin or owner enable developer mode if needed.
  3. Go to Settings -> Connectors -> Create.
  4. Name the connector Flick.
  5. Use https://api.joinflick.co/mcp as the connector URL.
  6. Open a new chat, click +, choose More, select Flick, and ask for account signal context.

Troubleshooting

Symptom Likely cause Fix
401 Authorization Bearer token is required Missing bearer token; the response should include WWW-Authenticate. Reconnect through OAuth or set FLICK_MCP_TOKEN.
403 MCP scope ... is required Token lacks user:org:read or the exact internal tool scope. Re-authorize with the required OAuth scope or request updated workspace access.
Account context is empty. No fresh persisted Play context snapshot for that account. Run account research or source tracking in Flick, then retry.
Claude.ai or ChatGPT cannot connect. The MCP endpoint is not reachable from vendor cloud infrastructure. Use the public HTTPS URL, not localhost or a private VPN URL.

References

Contact team@joinflick.co for workspace access.