flowIQ for developers

flowIQ maps how teams actually work: captures (recorded walkthroughs and interviews) become step-by-step workflows, and multiple captures of the same process get synthesized into one process map. this page documents the hosted mcp server that lets ai agents read and act on that data.

hierarchy: workspace (organization) > teams > processes > captures.

getting started

1. sign in at app.simplestuff.ai and open settings > api keys (click your name in the sidebar, then workspace settings).
2. create a key. it starts with fiq_ and is shown once - store it somewhere safe. we only keep a hash.
3. connect an mcp client (below) or call the endpoint directly over json-rpc.

# quickest check: list the tools your key can call
curl -X POST https://app.simplestuff.ai/api/mcp \
  -H "Authorization: Bearer fiq_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

authentication

every request needs an api key, sent as Authorization: Bearer fiq_... or X-API-Key: fiq_.... keys are user-wide: one key works across every workspace you are a member of, and each call can target a workspace via the workspace_id parameter.

• up to 10 active keys per user.
• revoking a key (settings > api keys) disables it immediately.
• keys inherit your permissions - nothing more. a key can never see workspaces you are not a member of.

connect a client

the mcp server lives at https://app.simplestuff.ai/api/mcp (streamable http, stateless - no session handshake required).

claude code

claude mcp add flowiq --transport http https://app.simplestuff.ai/api/mcp \
  --header "Authorization: Bearer fiq_YOUR_KEY"

claude desktop / other json config clients

{
  "mcpServers": {
    "flowiq": {
      "type": "http",
      "url": "https://app.simplestuff.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer fiq_YOUR_KEY"
      }
    }
  }
}

cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "flowiq": {
      "url": "https://app.simplestuff.ai/api/mcp",
      "headers": { "Authorization": "Bearer fiq_YOUR_KEY" }
    }
  }
}

github copilot (vs code)

vs code uses a servers key (not mcpServers) and can prompt for the key instead of storing it in the file:

// .vscode/mcp.json
{
  "inputs": [
    {
      "id": "flowiq-key",
      "type": "promptString",
      "description": "flowIQ api key (fiq_...)",
      "password": true
    }
  ],
  "servers": {
    "flowiq": {
      "type": "http",
      "url": "https://app.simplestuff.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${input:flowiq-key}" }
    }
  }
}

then open copilot chat in agent mode, click the tools icon, and enable the flowiq tools. vs code prompts for the key on first start and stores it encrypted. on github.com, copilot coding agent takes the same server config under repository settings > copilot > coding agent > mcp configuration (store the key as a copilot environment secret, not in the json).

microsoft copilot (copilot studio)

microsoft 365 copilot reaches mcp servers through a copilot studio agent - there is no json file; the server is added in the ui:

1. in copilot studio, open your agent and go to tools > add a tool > new tool > model context protocol.
2. server name flowiq, server url https://app.simplestuff.ai/api/mcp, and a short description (the orchestrator uses it to decide when to call the server - e.g. "reads and manages flowIQ process maps, captures and syntheses").
3. authentication: api key, type header, header name X-API-Key.
4. select create, then create a new connection and paste your fiq_ key as the api key value.
5. add to agent - the 30 tools appear on the agent's tools page. publish the agent to make it available in microsoft 365 copilot or teams.

copilot studio requires streamable http transport (sse is not supported) - our endpoint is streamable http, so no adapter is needed. note that power platform data policies apply: if your tenant regulates connectors, they also gate this mcp connection.

how scoping works

keys are user-wide, so the workspace is chosen per call. tools that operate at workspace level take an optional workspace_id:

• omit it and the call uses your first workspace - fine if you only have one.
• pass it explicitly when you belong to several. list_workspaces returns the ids.
• membership is re-validated on every call. a workspace_id, process or capture you cannot access answers not_found - existence is never revealed across workspaces.

recommended flow for agents:

1. list_workspaces to see the options.
2. list_teams / list_processes to find the process.
3. list_captures + get_capture for recorded detail, get_synthesis for the merged process-level view.

tool reference

30 tools. reads mirror what a member sees in the app; writes are real and follow the same permission rules as the ui.

rate limits

errors

tool-level failures come back as mcp results with isError: true and a json body like {"error": "process_not_found"} - they are not http errors.