MCP (Model Context Protocol)

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

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 adapter connection.

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

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 adapter
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 adapter 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 adapter 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 Adapters

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

Adapter	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 (adapter execution failed)