Guide

Connect Tidy via MCP

Tidy speaks Model Context Protocol (MCP) natively. Any MCP client — Claude Desktop, Cursor, Continue, a custom agent — can connect and gain live access to the unified graph.

Transport

The MCP endpoint is a Streamable HTTP transport at https://qa.tidy.engineering/api/v1/mcp. Auth is OAuth 2.1 (for production apps) or a Personal Access Token (for personal use + testing).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%\Claude\claude_desktop_config.json (Windows). Add the Tidy server block:

{
  "mcpServers": {
    "tidy": {
      "url": "https://qa.tidy.engineering/api/v1/mcp",
      "transport": "streamable-http",
      "oauth": {
        "authorize_url": "https://qa.tidy.engineering/api/v1/oauth/authorize",
        "token_url": "https://qa.tidy.engineering/api/v1/oauth/token",
        "scope": "basic_access"
      }
    }
  }
}

Restart Claude Desktop. On first use Claude will open a browser window for the OAuth consent flow. Approve the scopes you want to grant. Claude caches the token locally; subsequent calls are seamless.

Cursor

Add to your Cursor settings.json. Cursor supports MCP servers with a direct bearer token (PAT):

{
  "mcp.servers": {
    "tidy": {
      "url": "https://qa.tidy.engineering/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TIDY_PAT"
      }
    }
  }
}

Create a PAT in Tidy under Settings → Security → Personal Access Tokens (or with POST /api/v1/pats). Reload Cursor. The Tidy tools will appear in the composer tool list.

Custom MCP client

Tidy is a standard MCP streamable-HTTP server — any SDK from the modelcontextprotocol organization will connect.

from mcp import ClientSession, StreamableHttpClientTransport
import os

pat = os.environ["TIDY_PAT"]
transport = StreamableHttpClientTransport(
    url="https://qa.tidy.engineering/api/v1/mcp",
    headers={"Authorization": f"Bearer {pat}"},
)

async with ClientSession(transport) as session:
    await session.initialize()
    tools = await session.list_tools()
    for tool in tools.tools:
        print(tool.name, "-", tool.description)

What tools are exposed?

The MCP tool surface is generated from the OpenAPI spec plus the scope catalog. You can enumerate it live over the wire (list_tools) or by hitting https://qa.tidy.engineering/api/v1/mcp/manifest for a static snapshot.

Scopes on your token control which tools appear. A token with email:read sees the email read tools; one with full_agent sees everything.

Step-up consent

Sensitive operations — email:send, sms:send, write operations on calendar, large deletes — trigger a consent elicitation prompt in-client. The agent surfaces the prompt; the human approves. See Scopes for the full capability matrix.