Authentication

Layer’s MCP server supports a business-scoped connection mode. You can point an MCP client (Claude Desktop, an agent, MCP Inspector) at a single Layer business using a Layer API access token. The MCP server validates that token exactly the way the Layer API does and forwards it verbatim to Layer. The business to be interacted with through the connection is fixed by the URL path; the token proves who the caller is. Layer remains the authorization boundary.

Endpoint

Send requests to the business-scoped MCP endpoint over the Streamable HTTP transport:

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>

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`

This authentication mechanism only allows you to access one business, specified in the URL path {businessId}, which is the Layer business UUID. It must be a business owned by the token’s client. The environment is inferred from the token’s scope claim, so the token and the MCP host must be from the same environment.

Authenticate For A Given Business

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
}

Point the MCP client at the business

Use .../mcp/b/<businessId> as the server URL and send the token as Authorization: Bearer <access_token>. Nothing else to configure.

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, make sure to restart your Claude Desktop application.

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 (not a valid Layer token)
`403 insufficient_scope`	Token’s scope is not a recognized Layer environment scope
`404` (from Layer)	Business not found or not owned by the token’s client

Token Lifetime

Typically, our platform customers building an MCP integration with their own agents wrap this connection in a small refresher that re-mints via client_credentials, or run a local MCP process that manages its own token refresh. Caveat: for a human’s Claude Desktop config, a pasted token stops working at expiry and must be re-pasted.

When To Use Business-Scoped Access

/mcp/b/{businessId}: one business per connection, fixed at configure time, using an existing Layer API token. This is ideal for Layer’s platform customers whose engineers manage a backend that uses their client ID & secret to mint business-scoped access tokens, handle token lifespan, and expose Layer’s MCP server tools within their own platform’s agents.

MCP Server

Business MCP

Platform MCP

Authentication

Endpoint

Authenticate For A Given Business

Errors

Token Lifetime

When To Use Business-Scoped Access

​Endpoint

​Authenticate For A Given Business

​Errors

​Token Lifetime

​When To Use Business-Scoped Access

Endpoint

Authenticate For A Given Business

Errors

Token Lifetime

When To Use Business-Scoped Access