Generate scoped personal access tokens to connect MerchantFlow MCP from headless environments - VMs, SSH sessions, CI runners, and dev containers - without an OAuth browser flow.

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

Use OAuth	Use a Personal Access Token
Claude Desktop, Cursor, Windsurf, VS Code on your laptop	Headless VM, SSH session, container, CI job
Any client that can open a browser	Any client that cannot
You want auto-refresh and short-lived access tokens	You want a long-lived static credential to paste once

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)
Owner or admin role - PATs are scoped to your user, but only authorized roles can generate them

How to Generate a Token

Log in to dashboard.merchantflow.ai
Go to Settings > Developer > MCP (/dashboard/settings/developer/mcp)
Scroll to Personal access tokens and click Generate new token
Fill in:
- Name - a description so you remember where you used it (e.g. "GitHub Actions weekly P&L sync", "Workstation 1")
- Scopes - the read scopes the token can use (see below)
- Expires in - 30 days, 90 days, 180 days, or 1 year
Click Create token
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.

Available Scopes

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

Scope	What it grants
`mcp:pnl:read`	Profit & loss, revenue, expenses, and bank balance
`mcp:products:read`	Product profitability, COGS, and viability data
`mcp:ads:read`	Ad spend, ROAS, and attribution across Meta, Google, TikTok, Snapchat
`mcp:customers:read`	Cohort and LTV data (PII redacted by default)
`mcp:valuation:read`	Business valuations and sensitivity analysis
`mcp:north-star:read`	North Star metrics and goal progress
`mcp:activity:read`	Anomalies, alerts, and recent tenant activity

Pick only the scopes the client needs - if it only reads ad spend, do not give it customer or valuation access.

Using the Token

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

Authorization: Bearer mfp_<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://mcp.merchantflow.ai/mcp",
      "headers": {
        "Authorization": "Bearer mfp_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 prefix (mfp_xxxx...) plus its metadata, never the full secret.

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 Create. 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. The Plus tier rate limit (60 MCP calls per minute) applies to PAT-authenticated calls the same way it applies to OAuth-authenticated calls.

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.

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 Cursor - OAuth-based IDE install

Last updated: April 30, 2026

MCP Personal Access Tokens (Headless Connections)