MCP authentication

Fluveo MCP takes two kinds of credential. A client a person runs can sign in with OAuth: the person consents in the Dashboard, and the client holds a short-lived token with no key to copy. MCP sign-in with OAuth covers that way. Any client can use an agent key, and this page covers keys. An agent key is a restricted test key (rk_test_...) that you mark for an AI agent when you create it in the Dashboard. The client sends it with every request as Authorization: Bearer rk_test_.... Give each agent its own key, with only the permissions it needs.

What the server accepts#

The server reads the form of the Bearer value first. A value shaped like an OAuth access token, three parts joined by dots, goes to the token checks of MCP sign-in with OAuth. The server refuses any other value that does not start with rk_test_ before it checks the key anywhere. It then looks up a restricted test key among your store's keys.

The Fluveo MCP server is not available in production yet.

Create an agent key#

1. Switch to test mode#

   Sign in to the Dashboard. Check that the bottom of the sidebar shows Test mode. The form offers the agent mark only in test mode.

2. Open the API keys screen#

   Open Settings in the sidebar and go to the API keys section.

3. Start a restricted key#

   Under Restricted keys, click Create restricted key. In Key name, name the key after the agent that will use it, such as the client and the machine it runs on.

4. Mark the key for an AI agent#

   Check This key is for an AI agent. The hint under the box reads "Agent keys work in test mode only." You cannot add or remove the mark after the key exists.

5. Choose the permissions#

   Under Permissions, choose None, Read or Write for each resource. Give Read on each resource the agent may see, and Write only on a resource it may change. Write includes Read. Give Read on Account so the agent can call get_account_info. Permissions lists the paths each resource covers.

6. Copy the key once#

   Click Create key. The Dashboard shows the full key once, then only a masked hint. Copy it into the environment variable FLUVEO_MCP_KEY of the shell that starts your client, so no file holds the key.

   bashCopy

   read -rs FLUVEO_MCP_KEY && export FLUVEO_MCP_KEY

The client configuration names the variable, never the key. Connect a client has the configuration for each client.

Why not a secret key#

• A secret key calls every endpoint your store may use. In the Dashboard, the Standard keys section that holds it says such a key "unlocks full API access". An agent key calls only what its permissions allow.
• A secret key carries no agent policy. Its calls do not wait for agent approval, but the API's other checks still apply.
• Fluveo MCP refuses it. A secret key gets 401 with agent_key_required before the server checks it anywhere.

What the agent mark changes#

The mark tells the API that an AI agent holds the key. The API applies the agent policy to every call made with that key, whether the call comes through Fluveo MCP or goes to the API directly. The key's permissions still apply first. Then each operation has one of three outcomes:

• It runs. An operation the policy allows runs as it would for any restricted key with the same permissions.
• It waits for a person. An operation that needs approval answers approval_required and changes nothing until a person approves it in the Dashboard. Approvals shows the flow.
• It is refused. An operation the policy denies, or one it does not list, answers 403 even when the key holds the permission. Tools says what an agent cannot run.

Where the mark shows, and how long it lasts:

• The key list shows an AI agent badge next to the key's type.
• Edit key shows Agent key with the note "Set when the key was created. It can't be changed." The form has no control that removes the mark.
• Rotate key gives the new key the same name, permissions, note and mark.

The Dashboard offers the mark only on a restricted key created in test mode.

Permissions#

The tools a client sees depend on the key's permissions. A tool that needs a permission appears in tools/list only when the key has it. get_account_info, and the resource fluveo://account/summary, need Read on Account.

get_account_info answers the key's permissions as an object. Each name is a resource from Permissions, and each value is read or write. A resource with Write shows write, since Write includes Read.

{
  "permissions": { "account": "read", "customer": "read", "payment_intent": "write" }
}

The API checks the permission of every operation the agent runs. When the key lacks it, the tool answers an error that carries the API's 403. Its message names the permission that would allow the call, such as rak_customer_read. Add that permission with Edit key, and the agent mark stays as it is.

A restricted key without the mark#

Fluveo MCP refuses a restricted test key made without This key is for an AI agent. The request gets 401 with agent_key_required, and the message reads "This restricted key is not made for an AI agent. Make a restricted test key for an AI agent in the Dashboard under Settings > API keys." You cannot add the mark to an existing key, so create an agent key, put it in FLUVEO_MCP_KEY, and expire the old key if nothing else uses it.

Rotate and revoke#

Give each agent its own key. You can then end one agent's access without touching the others.

See each agent key#

Open Settings > Developers > AI agents in test mode. The Connections list shows each agent key of the store that still works, and no other key. After the keys come the apps connected with OAuth, which MCP sign-in with OAuth describes. Each key's row shows:

• The key's name, or Agent key when it has none, with the AI agent badge. A key you rotated with a timed expiration also shows Expires and the time it stops.
• The key's hint. The full key never shows.
• When the key was made and when it was last used, or never used.
• How many resources it may read and how many it may write, such as 3 read · 1 write. Click it to list each resource and its access.

Create an agent key opens API keys. Owners, admins and developers of the store see the list. In live mode the list says Agent keys are in test mode.

Revoke one agent key#

1. In Connections, find the row of the agent's key by its name and hint.
2. Click Revoke on that row. The Revoke agent key panel names the key's hint.
3. Click Revoke key. The Dashboard shows "Agent key revoked. The agent can no longer call Fluveo with it." and the row leaves the list.

Only an owner or an admin can revoke. A developer sees Revoke turned off, with the reason "Only owners and admins can revoke agent keys." A revoked key cannot be restored. Your other keys keep working.

To stop every agent of the store at once instead, turn off Allow AI agent access, as Security shows.

From the API keys screen#

The menu of each row in the key list under Settings > API keys has these actions:

• Expire key ends the key. In Expire API key, click Expire key again. The key cannot be restored. Your other keys keep working.
• Rotate key makes a new key with the same name, permissions, note and mark. In Expiration, choose when the old key stops: Now, or in 1 hour, 24 hours, 3 days or 7 days. To keep access during rotation, choose a timed expiration and put the new key in FLUVEO_MCP_KEY before the old one stops. Now revokes the old key during rotation, before the new key is shown.
• Edit key changes the key's name, note and permissions. It never changes the mark.

Fluveo MCP stops admitting a revoked or expired key within 3 seconds. From then on the key gets 401 with api_key_expired, and the message says the key "has expired or was revoked".

Errors#

The server answers these before any tool runs. Each body is {"error": {"type", "code", "message"}}.

Next#