> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Connect an MCP client to a single Layer business using a business-scoped access token.

Layer's MCP server supports a business-scoped connection mode. You can point an MCP client (Claude Desktop, an agent, [MCP Inspector](https://github.com/modelcontextprotocol/inspector)) at a single Layer
business using a [Layer API access token](/api-details/authentication). 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

<Steps>
  <Step title="Mint a Layer API token">
    This is the same client credentials flow used for the Layer REST API. See [Authentication](/api-details/authentication) for full details.

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "access_token": "...",
      "expires_in": 3600
    }
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`:

    ```json theme={null}
    {
      "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.

    <Note>
      The `${AUTH_HEADER}` env indirection avoids a Claude Desktop bug that splits `--header "Authorization: Bearer ..."` on the space.
    </Note>
  </Step>
</Steps>

## 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.