MCP (Model Context Protocol)

Attlaz exposes your connections as MCP tools, allowing AI assistants like Claude, Cursor, and other MCP-compatible clients to interact with your connected services directly.

This is the canonical MCP page

Everything about MCP — the scoping model, OAuth, and connecting a client — is documented here. The per-product MCP pages only list which tools that product's connections expose, and link back here.

Overview

The Model Context Protocol (MCP) is an open standard for connecting AI tools to external data sources and services. Attlaz implements the Streamable HTTP transport, providing a single POST endpoint per connection.

Every operation registered on a connector automatically becomes available as an MCP tool — no extra configuration needed.

Scoping

MCP access is scoped to a single connection. One connection is one MCP server URL with one token, and the tools it offers are the operations that connection's connector exposes.

A client that needs two connections is configured with two URLs.

Scope	Endpoint	Status
Connection	`POST /mcp/{connectionId}`	Available
Project	`POST /mcp/project/{projectId}`	Planned
Product	—	Planned

Planned — not shipped yet

Only the connection scope exists today. Project-scoped and product-scoped MCP are designed but not built: there is no endpoint to call, and no token audience to request for them. Build against the connection scope.

The planned project scope consolidates every connection in a project behind one URL, with a connection_id argument on each tool to pick between them, and a consent step where you choose which connections a token may act on. The planned product scope narrows that to the connections a single product uses.

Endpoint

POST https://api.attlaz.com/mcp/{connectionId}

All MCP communication happens over this single endpoint using JSON-RPC 2.0 messages. Authentication uses an OAuth 2.0 Bearer token — see Authentication for details on how MCP tokens are scoped.

Authentication

MCP requests use an OAuth 2.0 Bearer token, with one MCP-specific addition: audience binding per RFC 8707.

Audience binding

When you request a token from /oauth/token, include the MCP resource as the audience:

curl -X POST https://api.attlaz.com/oauth/token \
  -d 'grant_type=...' \
  -d 'client_id=...' \
  -d 'resource=https://api.attlaz.com/mcp'

The returned token is bound to /mcp/* and cannot be used against other API surfaces (/projects, /flows, …). A token issued without resource=https://api.attlaz.com/mcp will receive 403 Forbidden on any /mcp/* request.

This is defense-in-depth: if an MCP client's token is compromised, the blast radius is limited to the MCP surface.

Discovery

Spec-compliant MCP clients can discover everything they need from two well-known endpoints:

URL	RFC	Purpose
`https://api.attlaz.com/.well-known/oauth-authorization-server`	RFC 8414	Authorization server metadata (token endpoint, supported grants, PKCE methods)
`https://api.attlaz.com/.well-known/oauth-protected-resource/mcp`	RFC 9728	Protected resource metadata (resource URL, linked authorization servers)

An unauthenticated request to any /mcp/* endpoint returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata:

WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://api.attlaz.com/.well-known/oauth-protected-resource/mcp"

Clients following RFC 9728 §5 follow this link, read the metadata, and obtain a correctly-scoped token automatically.

Supported Methods

Method	Description
`initialize`	Handshake — returns server info and capabilities
`tools/list`	Lists all available tools for the connection's connector
`tools/call`	Executes a tool with the given arguments

Setup

Claude Code

Add to your MCP configuration (.mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "attlaz": {
      "type": "streamableHttp",
      "url": "https://api.attlaz.com/mcp/{connectionId}",
      "headers": {
        "Authorization": "Bearer {TOKEN}"
      }
    }
  }
}

Replace {connectionId} with the ID of your connection and {TOKEN} with your Attlaz access token.

Other MCP Clients

Any MCP client that supports Streamable HTTP transport can connect. Configure it with:

URL: https://api.attlaz.com/mcp/{connectionId}
Method: POST
Header: Authorization: Bearer {TOKEN}
Content-Type: application/json

Protocol Details

Initialize

curl -X POST https://api.attlaz.com/mcp/{connectionId} \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0" }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "Attlaz", "version": "1.4.0" }
  }
}

List Tools

curl -X POST https://api.attlaz.com/mcp/{connectionId} \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Returns all available operations for the connector behind this connection, each with a JSON Schema describing its input parameters.

Call a Tool

curl -X POST https://api.attlaz.com/mcp/{connectionId} \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "tailFile",
      "arguments": { "path": "/var/log/syslog", "lines": 50 }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{\"content\": \"...\", \"lineCount\": 50}" }
    ]
  }
}

Available Connectors

Any connection in Attlaz can be used via MCP. The tools available depend on the connector type. Currently supported connectors include:

Connector	Example Tools
SSH	`listFiles`, `readFile`, `tailFile`, `searchFile`, `getFileInfo`, `listDirectories`
Google Sheets	`getSheetValue`, `setSheetValue`, `clearSheet`
OpenAI	`prompt`
Philips Hue	`listLights`, `getLightState`, `setLightState`, `listDevices`

Use tools/list to discover all available tools for a specific connection.

Error Handling

Errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32603,
    "message": "SSH connection not configured"
  }
}

Code	Meaning
`-32600`	Invalid Request (malformed JSON-RPC)
`-32601`	Method not found
`-32602`	Invalid params
`-32603`	Internal error (connector execution failed)

Overview​

Scoping​

Endpoint​

Authentication​

Audience binding​

Discovery​

Supported Methods​

Setup​

Claude Code​

Other MCP Clients​

Protocol Details​

Initialize​

List Tools​

Call a Tool​

Available Connectors​

Error Handling​