MCP Tokens

Overview

MCP Tokens let you issue short-lived tokens that carry specific permissions. Instead of sharing your full API key, you create an MCP Token that grants only the access needed for a particular use case — a dashboard widget, a third-party integration, or an MCP-connected AI client.

MCP Tokens are prefixed with mcp_tbac_ and are validated alongside your API key. When a token expires or is revoked, access stops immediately — no key rotation required.

Why Use MCP Tokens?

Available Scopes

Combine scopes by selecting multiple when creating the token.

Generating a Token

1. Open the Floopy dashboard and navigate to Settings > Access Tokens
2. Click New Token
3. Enter a name (e.g., claude-desktop-mcp)
4. Select the desired scopes
5. Set an expiration — choose from preset durations or a custom date
6. Click Generate
7. Copy the token immediately — it is shown only once

Token Expiration

Tokens can be set to expire after:

When a token expires, requests using it receive a 401 Unauthorized response with the message "token expired". Issue a new token to restore access.

Revoking a Token

To revoke a token immediately:

1. Go to Settings > Access Tokens
2. Find the token by name
3. Click Revoke

Revoked tokens are invalidated within seconds — all requests using that token will fail with 401 Unauthorized. This is useful when a token is compromised or a partnership ends.

Using an MCP Token

Pass the token as a Bearer token, identically to an API key:

Authorization: Bearer tbac_your_token_here

With OpenAI SDK:

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_TBAC_TOKEN,  // tbac_... token
});

With MCP client:

{
  "mcpServers": {
    "floopy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.floopy.ai/mcp"],
      "env": {
        "MCP_AUTH_TOKEN": "tbac_your_token_here"
      }
    }
  }
}

Scope Enforcement

If a token lacks the required scope for an operation, the gateway returns:

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have scope: mcp:analytics:read",
    "required_scope": "mcp:analytics:read"
  }
}

Security Best Practices

Principle of least privilege Issue tokens with only the scopes needed for the task. A token that only needs to list models should not have gateway:route access.

Short expiration windows Prefer short-lived tokens over permanent ones. Automate token refresh in your integration rather than issuing never-expiring tokens.

One token per integration Create a separate token for each service, client, or partner. This lets you revoke access for one without affecting others.

Rotate regularly Even long-lived tokens should be rotated periodically. Set a calendar reminder to regenerate tokens every 30–90 days.

Do not log tokens MCP Tokens provide real access. Treat them like passwords — never log them, commit them to version control, or include them in error messages.

Use Floopy Vault for MCP secrets When configuring MCP server credentials inside a plugin YAML, always use secret_ref pointing to Floopy Vault. Never inline an MCP Token or API key in the YAML itself.

Token Audit Log

Every token usage is recorded in the audit log:

• Timestamp of the request
• Token name (not the token value)
• Scope used
• Endpoint called
• IP address

View the audit log under Settings > Access Tokens > Activity.

Availability

MCP Tokens are available on the Pro plan and above.