Authentication

Connect an MCP client in platform mode, provisioned business mode, or Layer-token passthrough.

Layer’s MCP server supports three Streamable HTTP URLs. The JWT proves who the caller is. Which URL you hit selects platform vs business mode and which capability groups are registered by default.

Hosts:

Environment	MCP host	Layer API scope
Sandbox	https://mcp-sandbox.layerfi.com	https://sandbox.layerfi.com/sandbox
Production	https://mcp.layerfi.com	https://api.layerfi.com/production

The environment is inferred from the token’s scope claim, so the token and the MCP host must be from the same environment. Layer remains the authorization boundary.

Platform: /mcp

POST   https://mcp.layerfi.com/mcp
GET    https://mcp.layerfi.com/mcp
DELETE https://mcp.layerfi.com/mcp
Authorization: Bearer <mcp-client-jwt>

Platform mode is for operators who move between businesses. The agent must call set_active_business with a Layer business UUID before business-scoped tools. Default groups are core and reporting. Extra groups can be set on the provisioned client (capabilityGroups) or with LAYER_MCP_GROUPS.

Platform mode does not register accounting mutations. See Platform session.

Provisioned business: /mcp/:businessToken

POST   https://mcp.layerfi.com/mcp/{businessToken}
GET    https://mcp.layerfi.com/mcp/{businessToken}
DELETE https://mcp.layerfi.com/mcp/{businessToken}
Authorization: Bearer <mcp-client-jwt>

The business is fixed at provisioning (layerBusinessId on the MCP server client entry). There is no set_active_business tool. Default groups are core, reporting, and accounting. Additional groups (banking_imports, ar_imports, ap_imports, loans_assets, qbo) are opt-in via capabilityGroups or LAYER_MCP_GROUPS.

Use this when Layer (or the platform) has already issued a per-business MCP URL token for an interactive client.

Passthrough business: /mcp/b/{businessId}

Point an MCP client at a single Layer business using a Layer API access token. The MCP server validates that token the same way the Layer API does and forwards it verbatim to Layer.

POST   https://mcp.layerfi.com/mcp/b/{businessId}
GET    https://mcp.layerfi.com/mcp/b/{businessId}
DELETE https://mcp.layerfi.com/mcp/b/{businessId}
Authorization: Bearer <layer-api-access-token>

{businessId} is the Layer business UUID. It must be a business owned by the token’s client.

Passthrough registers all business capability groups (core, reporting, accounting, banking_imports, ar_imports, ap_imports, loans_assets, qbo) unless LAYER_MCP_GROUPS is set on the MCP server.

This is the right fit when platform engineers already mint Layer API tokens and want to expose Layer MCP tools inside their own agents.

Authenticate for a given business (passthrough)

1. Mint a Layer API token

   This is the same client credentials flow used for the Layer REST API. See Authentication for full details.

   curl -X POST https://auth.layerfi.com/oauth2/token \
     -u "$LAYER_CLIENT_ID:$LAYER_CLIENT_SECRET" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=$LAYER_CLIENT_ID&scope=https://sandbox.layerfi.com/sandbox"
   

   The authorization server responds with a short-lived access token:

   {
     "access_token": "...",
     "expires_in": 3600
   }
   
2. Point the MCP client at the business

   Use …/mcp/b/<businessId> as the server URL and send the token as Authorization: Bearer <access_token>.

3. Configure Claude Desktop for testing (optional)

   Claude Desktop runs OAuth discovery on remote servers, so pass the static bearer through the mcp-remote proxy in ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "layer-sandbox": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://mcp-sandbox.layerfi.com/mcp/b/<businessId>",
           "--header", "Authorization:${AUTH_HEADER}"
         ],
         "env": { "AUTH_HEADER": "Bearer <access_token>" }
       }
     }
   }
   

   After making this change, restart Claude Desktop.

   The ${AUTH_HEADER} env indirection avoids a Claude Desktop bug that splits --header "Authorization: Bearer ..." on the space.

Errors

Status	Meaning
401	Missing or malformed bearer, or JWT invalid/expired/wrong issuer
403 insufficient_scope	Token’s scope is not a recognized Layer environment scope (passthrough) or required MCP scope (provisioned)
404	Provisioned business token not found, or (from Layer) business not found / not owned by the token’s client

Token lifetime

Platform customers building an MCP integration typically wrap passthrough in a refresher that re-mints via client_credentials, or run a local MCP process that manages token refresh.

For a human’s Claude Desktop config, a pasted token stops working at expiry and must be re-pasted.

When to use which URL

Need	URL
One agent across many businesses	/mcp (platform)
Interactive client, business fixed at provisioning	/mcp/:businessToken
Existing Layer API token, one business in the path	/mcp/b/{businessId}