MCP Personal Access Tokens (Headless Connections)

MCP Personal Access Tokens

Personal access tokens (PATs) let you connect MCP clients that cannot complete a browser-based OAuth flow - virtual machines, SSH sessions, CI/CD runners, dev containers, or any headless environment. Generate a scoped token in MerchantFlow, paste it into the client's Authorization header, and you are connected.

When to Use a PAT vs OAuth

PATs are an alternative to the OAuth flow described in the main MCP guide. The same scoping, audit logs, and tenant isolation apply to both.

Prerequisites

• A MerchantFlow workspace on the Plus tier (MCP server access)
• Any signed-in member of that workspace can generate a token -- there is no additional role requirement. Tokens are scoped to the user who created them, and each person manages their own.

How to Generate a Token

1. Log in to merchantflow.ai
2. Go to Settings > Developer > MCP (/dashboard/settings/developer/mcp)
3. Scroll to Personal access tokens and click Generate new token
4. Fill in:
   • Name - a description so you remember where you used it, up to 100 characters (e.g. "GitHub Actions weekly P&L sync", "Claude on server-vm-1")
   • Expires after - 30 days, 90 days, 180 days, or 1 year (defaults to 90 days)
   • Scopes - the read scopes the token can use, at least one required (see below)
5. Click Generate token
6. Copy the token immediately. MerchantFlow shows the full secret exactly once and stores only a one-way hash afterward. Lost tokens cannot be recovered - you have to generate a new one.

Token Format

Tokens look like mf_pat_ followed by 32 hexadecimal characters:

mf_pat_a1b2c3d4e5f60718293a4b5c6d7e8f90

The mf_pat_ prefix is how the MCP server tells a personal access token apart from an OAuth access token, so never strip or alter it.

Available Scopes

Tokens are scoped to one or more read-only MCP scopes:

Pick only the scopes the client needs - if it only reads ad spend, do not give it customer or valuation access. The create-token dialog has a Select all shortcut if you want the equivalent of full read access.

See the tool reference for exactly which tools each scope unlocks.

Using the Token

Send the token as a Bearer credential in the Authorization header on requests to https://merchantflow.ai/api/mcp:

Authorization: Bearer mf_pat_<your-token>

How you wire that up depends on the client. Most MCP clients accept an Authorization header in their server config. Example for clients that take an headers object:

{
  "mcpServers": {
    "merchantflow": {
      "url": "https://merchantflow.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer mf_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For CI/CD pipelines, store the token as a secret (e.g. GitHub Actions secrets.MERCHANTFLOW_MCP_TOKEN) and reference it from the workflow.

Managing Tokens

From Settings > Developer > MCP > Personal access tokens (/dashboard/settings/developer/mcp) you can:

• See every token you have created (name, prefix, scopes, expiry, last-used time)
• Revoke a token immediately - this kills the credential server-side and the client stops being able to call the MCP
• Track when each token was last used to spot abandoned credentials

The token list shows only the first 12 characters as a prefix (mf_pat_a1b2c...) plus its metadata, never the full secret. The last-used timestamp updates at most once every 5 minutes, so a very recent call may not appear immediately.

You only see the tokens you created yourself. Tokens created by other people in your workspace are managed from their own accounts.

Security Best Practices

• Never commit tokens to source control. Use environment variables or secret managers.
• Use the minimum scope set that the client actually needs.
• Choose the shortest expiry that fits the use case. 30 days for one-off scripts, 90-180 days for ongoing CI jobs, 1 year only for stable infrastructure with rotation policies.
• Rotate tokens regularly by generating a new token, updating your client, and revoking the old one.
• Revoke tokens immediately if a machine is decommissioned, an employee leaves, or you suspect a credential leaked.

All MCP calls - whether authenticated by OAuth or PAT - are logged in your audit trail. Open Settings > Developer > MCP (/dashboard/settings/developer/mcp) to inspect recent activity.

Frequently Asked Questions

Can I see the token after I close the create dialog?

No. MerchantFlow stores only a one-way hash of the token after you click Generate token. The plaintext secret is shown exactly once. If you lose it, generate a new one.

How many tokens can I have at once?

There is no published hard cap. Generate one per environment (CI, dev VM, etc.) so you can revoke them independently.

Do tokens follow the same rate limit as OAuth clients?

Yes. Rate limits are per workspace, not per credential: 60 standard tool calls per minute, 10 heavy tool calls per minute, and 2,000 calls per day. PAT and OAuth traffic share the same buckets, and the same numbers apply to every workspace.

Are tokens tenant-scoped?

Yes. A token can only call tools in the workspace where it was created. Cross-tenant access is impossible even if the token leaks.

What happens when a token expires or is revoked?

The next MCP call fails with a 401 and an invalid_token error. Generate a replacement token and update the client's Authorization header. Revocation and expiry both take effect immediately - there is no grace period.

My OAuth client connected fine but every call now returns 401

If the error text says the access token "was issued before the current authorization format. Disconnect and reconnect MerchantFlow in your AI client to get a new one", the client is still holding an old token that is not bound to your store. Disconnect and reconnect it -- the token endpoint now binds every newly issued token to https://merchantflow.ai/api/mcp automatically, so the reconnect succeeds. A personal access token is the alternative if you would rather not repeat the browser flow.

Can I use a PAT instead of OAuth from Claude Desktop?

Most desktop clients are designed to use OAuth and will work fine with the standard flow. Use PATs for environments that cannot open a browser.

Related Guides

• MCP Server Overview - what MCP is and what tools are available
• Tool Reference - the full read-only tool catalog
• Connect Claude Desktop - OAuth-based desktop install
• Connect Claude Code - CLI install, with a PAT flag for headless machines
• Connect Cursor - OAuth-based IDE install

Last updated: August 29, 2026