MCP server

Flowstate’s MCP server lets Claude, ChatGPT or another AI assistant read your Flowstate data and make changes in a scenario. You ask a question in the assistant, and it looks up the answer in Flowstate. It acts as you: it sees only what you can see in Flowstate, and changes only what you can change.

You need MCP access switched on for your organisation. Ask your Flowstate contact.

Choose your assistant

Connect any other assistant

1. In Flowstate, select Ask Eddy in the top bar, then New chat (the +). Under Connect from Claude or ChatGPT, select Copy MCP URL. The address is your Flowstate address followed by /api/mcp/protocol, for example https://acme.flowstate.inc/api/mcp/protocol.
2. In your assistant, add a remote MCP server and paste that address.
3. When your assistant opens the Flowstate page, sign in with your Flowstate account and select Approve.

What you can ask

Try questions like these:

• “Who joins the Platform team next month, and what will they cost?”
• “What is the Payments team working on, and how much effort went into each project last quarter?”
• “Which teams spent the most on AI this month?”
• “How far has the forecast moved from the budget we locked in January?”
• “Which projects are completed but still have people allocated?”
• “Who hasn’t submitted their effort report for the last four weeks?”
• “How much capitalisable spend haven’t we claimed yet this year?”
• “Show me the functional structure under Engineering, with open seats.”

What it can change

In a scenario. Adding, moving or removing people, teams, vacancies, contractors, projects, allocations, budgets and AI agents happens in a scenario, never in live data. You see the changes in Flowstate, and they reach live data only when someone submits, approves and merges the scenario there. See Live data and scenarios.

In live data, straight away. Some changes apply as soon as the assistant makes them, exactly as if you’d made them in Flowstate:

• the budget workflow: budget requests and proposals
• initiatives, objectives and key results
• CapEx claims and capitalisation records
• functional groups, and who manages them
• which project your own AI sessions count towards

Not at all. It can’t approve or merge a scenario, lock a budget, change settings (apart from who may see functional group cost), or do anything your Flowstate role doesn’t allow.

Tool catalogue

These are the 107 tools the assistant can call. Every tool runs with the permissions of the person who connected: if you can’t see salaries in Flowstate, a tool that needs them refuses or leaves them out. Where a tool needs a permission most people don’t have, it’s noted.

Start here

People and teams

Projects, initiatives and objectives

Effort

Effort tools default to the last three months; pass startDate and endDate to change the period.

Analytics and the forecast

query_analytics takes metrics, dimensions and dataSource (ACTUAL, FORECAST or SUBMISSION), plus optional startDate, endDate, timeGranularity (MONTH, QUARTER or YEAR), filters, costSection, and sort, order and limit for top-N questions (limit is at most 25). The tool’s own description lists every metric and dimension. For AI spend examples, see AI usage.

Budgets

CapEx and R&D

The three breakdowns take submittedOnly: true counts submitted effort only, false includes effort still in draft. It defaults to false, except on get_capex_declared_vs_claimed, where it defaults to true.

Code delivery

Need View Effort Tracking. Cost per person needs View Financial Summary.

AI and insights

For AI spend and usage by team, person, provider or model, use query_analytics.

Functional groups

Both take asOf (a day, YYYY-MM-DD, default today) and an optional planId to read a scenario.

Change a scenario

Every tool here needs Edit Scenario Plans and a planId for a scenario that’s still a draft. Create one first with create_scenario.

Change functional groups

These change live data unless you pass a planId. Each follows the functional group’s own access: Edit all functional groups, or being a manager of the group or a group above it. The tools refuse with FEATURE_DISABLED if your organisation doesn’t have functional groups. See Map your functional organisation.

Change budgets

These change live data, and work through the same steps as the budget workflow in Flowstate.

Change initiatives, objectives and CapEx

These change live data. They take no planId.

Your own AI sessions

If something’s not right

“MCP external access is not enabled for this organization” — MCP is switched off for your organisation. Ask your Flowstate contact.

There’s no Connect from Claude or ChatGPT box in Eddy — MCP isn’t switched on for your organisation yet.

“User is inactive or not a member of this organization” — your Flowstate account has been deactivated or moved to another organisation. Ask a Flowstate admin, then connect again.

The assistant says you don’t have permission — your Flowstate role doesn’t allow it. Salaries and costs, for example, need a financial permission. Ask a Flowstate admin.

A scenario change is refused — the scenario isn’t a draft any more, or it belongs to a budget proposal that’s been submitted. Create a new scenario, or reopen the proposal in Flowstate.

“Rate limit exceeded. Try again shortly.” — you’ve made too many requests in a minute. Wait a minute and ask again.

To disconnect, remove the Flowstate connector from your assistant. If MCP is switched off for your organisation, every connection stops working straight away.

For developers

This part is for people building their own MCP client or checking a connection.

Transport and endpoint

The server speaks MCP over Streamable HTTP, without sessions:

https://{tenant}.flowstate.inc/api/mcp/protocol

Every protocol request carries the access token:

POST /api/mcp/protocol
Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Tool results come back as a single text content item holding JSON. A tool refuses in one of two ways: its JSON has an error field, or the result is marked isError: true with the reason as text. A missing permission reads Forbidden: You do not have the required permission: ….

Authentication

MCP uses OAuth 2.0 authorisation code with PKCE. Each person signs in with their own Flowstate account. There’s no API key for MCP: REST API keys from Settings → Users & Access → API Keys don’t work on /api/mcp/protocol, and MCP connections don’t appear on that page.

1. Discover. GET /.well-known/oauth-authorization-server on your Flowstate address:

{
  "issuer": "https://{tenant}.flowstate.inc",
  "authorization_endpoint": "https://{tenant}.flowstate.inc/api/mcp/oauth/authorize",
  "token_endpoint": "https://{tenant}.flowstate.inc/api/mcp/oauth/token",
  "registration_endpoint": "https://{tenant}.flowstate.inc/api/mcp/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "scopes_supported": ["openid", "profile"]
}

2. Register. No authentication needed:

POST /api/mcp/oauth/register
Content-Type: application/json

{ "client_name": "My assistant", "redirect_uris": ["https://example.com/callback"] }

• client_name is required, at most 200 characters.
• redirect_uris holds one to five addresses, each https, or http on localhost, 127.0.0.1 or [::1].

The 201 response carries client_id and client_secret, with token_endpoint_auth_method: "client_secret_post". Registration is limited to 20 an hour per IP address.

3. Authorise. Send the person to /api/mcp/oauth/authorize with:

• response_type=code
• client_id and redirect_uri, which must be one you registered
• code_challenge and code_challenge_method=S256
• an optional state

If they aren’t signed in to Flowstate, they’re asked to sign in first. When they approve, you get code and state back on the redirect; if they deny, you get error=access_denied. Codes can be used once, within five minutes.

4. Exchange the code.

POST /api/mcp/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&client_id=<client id>&client_secret=<client secret>&redirect_uri=<redirect uri>&code_verifier=<PKCE verifier>

{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque>"
}

5. Refresh. Send grant_type=refresh_token with refresh_token, client_id and client_secret.

• Access tokens last an hour.
• Refresh tokens last 30 days.
• Each refresh returns a new refresh token, and the old one stops working.

Permissions aren’t stored in the token. Every call checks the person’s current Flowstate role, so a role change applies straight away. A person who’s deactivated, or whose organisation has MCP switched off, is refused on their next call.

Scenarios

Scenario writes take a planId:

1. Call create_scenario for a new scenario, or list_scenarios to find an existing one.
2. Pass its id as planId on each write.
3. Read it back with query_analytics, or the functional group reads, using the same planId.

A write is refused if the person doesn’t have Edit Scenario Plans, if the scenario belongs to another organisation, if it isn’t a draft, or if it backs a budget proposal that’s been submitted, is in review or has been approved. Merging happens in Flowstate. See Scenarios.

Rate limiting

Protocol requests are limited to 100 a minute per person, in fixed one-minute windows. POST responses carry:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: <0–100>

Over the limit:

HTTP/1.1 429 Too Many Requests

{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "Rate limit exceeded. Try again shortly." },
  "id": null
}

Errors

When a token expires, refresh it and retry. On 429, wait for the next minute.

Audit

Each protocol request is recorded as an audit event with:

• the MCP method
• the person, organisation and tenant
• the request ID, IP address and user agent

Consent, token issue, refresh and client registration are recorded too. If you’ve connected a SIEM, these events arrive there with the rest of Flowstate’s.

See also

• Connect Flowstate to Claude
• Connect Flowstate to ChatGPT
• AI usage — AI spend questions through query_analytics
• Scenarios — what REST and MCP can each do with scenarios