MCP

MCP OAuth and Access

How CurrencyCore MCP sign-in works, how organization selection is bound to a connection, what the client can access, and how to revoke it.

The CurrencyCore MCP server is a remote service, so it uses OAuth instead of an API key pasted into a config file. You sign in through your browser once, choose an organization, and the client keeps the resulting credential.

This page explains the user-facing flow. It does not document OAuth internals such as token formats or lifetimes, because those are managed by the client and the authorization server.

Status note. The 2026-11-11 release fixed MCP OAuth discovery: an unauthenticated request to /mcp now returns 401 with a WWW-Authenticate challenge, and the protected-resource metadata names the exact /mcp URL. If a client connected to an older deployment never opens a browser, see the troubleshooting note.

Why OAuth instead of an API key

An API key is a long-lived secret. Copying one into every client config makes it easy to leak, hard to scope to a person, and awkward to revoke when someone leaves a team.

OAuth changes the unit of access from “a key someone pasted” to “a signed-in user, a client application, and an organization”. That gives you:

No secret in the client config file. The URL is the only thing you add.
A browser consent step that names the organization being connected.
Access that follows the user’s membership. Removing a member removes their MCP access.
An organization-level switch that stops MCP traffic without touching REST keys.

You add the server URL https://mcp.currency-core.com/mcp to the client. You do not create an OAuth client or copy a client ID. The MCP client registers itself with the authorization server as part of the connection.
The server challenges the connection, and the client opens a browser the first time you connect or call any tool. The current server requires an authorized connection for every /mcp request, including the two reference tools.
You sign in to CurrencyCore with your normal account. If you are already signed in, the consent screen appears directly.
You choose one organization. Only organizations you belong to are available. The choice is recorded for this user and this client application.
You approve the connection and return to the client. The client stores the credential and sends it as a bearer token on MCP requests.

The connection is bound to the organization you chose. To switch organizations, reconnect the server in the client and choose a different one. A second client application is a separate grant, so it asks you to choose an organization again.

Metadata a client reads

The client discovers the authorization server from the WWW-Authenticate challenge on /mcp, then reads the protected-resource metadata at one of these paths:

Request	Purpose
`GET https://mcp.currency-core.com/.well-known/oauth-protected-resource/mcp`	Names the resource and the authorization server for the `/mcp` endpoint
`GET https://mcp.currency-core.com/.well-known/oauth-protected-resource`	The same metadata at the host root

The response names the resource, the authorization server, and the supported scope. The resource is the exact /mcp URL, not the bare host, and the scope is mcp:tools. The client then fetches the authorization server metadata from the URL named in that response and starts the browser flow.

You do not hard-code these paths in your client. A compliant MCP client follows the challenge and the metadata links. They are listed here so you can diagnose a connection that never opens a browser.

What the connection can access

An authorized connection exposes the full tool set that the organization’s plan allows:

Access	Included
Tools	All 14 tools are listed after sign-in. The two reference tools are unmetered. The seven `analyze_` tools require Growth or higher.
Resources	The bundled API docs and the OpenAPI 3.1 specification.
Prompts	`convert_with_ppp`, `compare_cost_of_living`, `build_rate_table`, `explain_error`.
Account changes	None. Every tool is read-only.
API keys	None. MCP does not mint or reveal an API key.
Billing changes	None. The connection cannot change a plan or payment method.

The client cannot create, rotate, or revoke REST API keys, invite members, change SSO settings, or read billing details. It can only fetch currency, PPP, and analytics data.

About scopes

The authorization server advertises standard OpenID Connect scopes (openid, profile, email, and offline_access) plus the baseline mcp:tools scope used by the connection challenge. There are no separate per-tool or per-endpoint scopes. In practice:

Any authorized connection can see every tool the plan allows.
Analytics gating is enforced by the API at call time, not by an OAuth scope.
There is no read-only versus read-write scope split, because every tool is already read-only.

Do not expect a consent screen that asks you to tick individual tools. It asks you to sign in and pick an organization.

Token handling

The access token stays inside the client. It is not returned in tool results.
You do not paste it into another client or into a config file.
If the token expires or the client loses it, the next keyed call asks you to sign in again.
Disconnecting in the client removes the local credential. Disabling MCP in the dashboard stops the organization’s keyed MCP traffic for every client.

Organization selection and membership

The organization you pick at consent is the one that pays for the calls and owns the usage. The monthly quota is shared by the organization.
Membership is revalidated on every request. If you are removed from the organization after connecting, the next keyed call fails even if the client still holds a token.
If you belong to no organization, you cannot complete an authorized connection. Create an organization first, or ask an owner to invite you.
A teammate using the same client signs in separately. They get their own grant and choose their own organization; they do not inherit yours.

Usage, limits, and the MCP switch

Each successful keyed tool call counts as one API request against the organization’s monthly quota. Public tool calls are free.
MCP uses no AI credits. The AI endpoint is HTTP-only and is not an MCP tool.
MCP traffic shares the organization’s per-minute limit and monthly quota with REST traffic.
The dashboard shows MCP usage in the Developer area, in the MCP server panel. The same panel has an enable/disable switch for the organization.

Disabling MCP does not revoke REST API keys, delete the organization, or change the plan. It stops keyed MCP calls for that organization. The switch is enforced by the API on the next tool call, so an existing client credential can keep the connection open but cannot complete a keyed call.

Disconnecting and revoking

Goal	What to do	Effect
Stop using the server in one client	Remove or disconnect the server in the client’s MCP settings	The client deletes its local credential. Other clients are unaffected.
Stop all MCP traffic for the organization	Turn off the MCP switch in Dashboard, Developer, MCP server	Keyed MCP calls return `403`. REST keys keep working.
Stop one person’s access	Remove them from the organization, or ask them to disconnect	Membership is revalidated per request, so their grant stops resolving.
Reconnect to a different organization	Disconnect in the client, add the server again, and choose the other organization	A new grant replaces the old one for that user and client.

There is no separate MCP API key to rotate. If you suspect a client credential was exposed, disconnect that client and disable the organization’s MCP switch while you investigate.

401 and 403 behavior

Status	Typical cause	What to do
`401 unauthorized`	No token, an expired token, a revoked client, or a grant that no longer resolves to an organization (for example, after membership removal)	Reconnect the server and sign in again. If it repeats, confirm you are still a member of the organization.
`403 forbidden`	MCP is disabled for the organization, the tool needs Growth or higher, or the requested history window is outside the plan	Read the message. Re-enable MCP, upgrade the organization, or narrow the date range.
`402 billing_past_due`	The organization’s billing is past due	API access is paused until payment clears. Test keys are exempt from the pause and stay capped at the Free rate limit; MCP connections are treated as live and return `402`.
`429 rate_limited`	The organization hit its per-minute limit or monthly quota	Wait for the window to reset, or upgrade. Read `currencycore/retry_after_s` in the tool result.

A 403 is not automatically an authentication problem. Re-signing in will not fix a plan gate or a disabled MCP switch. The troubleshooting guide separates these cases.