Skip to main content

MCP Quickstart

Use this path when the caller is an AI agent, not your own backend. The MCP server exposes Clocktower protocol tools so an agent can discover subscriptions, inspect accounts, and request prepared transactions through a standard tool interface.

Connect any MCP-compatible client to mcp.clocktower.finance. Access uses the same free rate limits and optional developer API keys (ctk_…) as REST — see REST authentication and rate limits. Protocol tools take optional chainId (default Base). See MCP chain selection.

Endpoint​

https://mcp.clocktower.finance

The client connects to the subdomain root — no /mcp path suffix.

Requirements​

  • MCP-compatible client with Streamable HTTP (or equivalent) transport
  • Optional developer API key (ctk_…) for higher limits
  • Wallet for signing prepared transactions

Add the server​

Point your MCP client at the endpoint. Example config used by many clients (free tier):

{
  "mcpServers": {
    "clocktower": {
      "url": "https://mcp.clocktower.finance"
    }
  }
}

To use a developer key, add "headers": { "Authorization": "Bearer ctk_…" } on that server entry. Then list tools (your client will show names such as get_protocol_state and search_subscriptions) and call them with the JSON arguments below.

Example: read protocol state​

Tool: get_protocol_state

{ "chainId": 8453 }

Tool: list_chains

{}

Tool: search_subscriptions

{ "first": 10 }

Example: read subscription​

Tool: get_subscription

{ "id": "0x..." }

Create a subscription​

amount is a human-readable token string (e.g. "10"), not protocol wei.

frequency is 0 weekly, 1 monthly, 2 quarterly, 3 yearly.

details.url and details.description may be empty strings.

Tool: prepare_create_subscription

{
  "from": "0xProviderAddress",
  "amount": "10",
  "token": "0x...",
  "details": { "url": "https://example.com/", "description": "Premium" },
  "frequency": 1,
  "dueDay": 15
}

Subscribe​

Tool: prepare_subscribe_by_id

{
  "from": "0xYourAddress",
  "id": "0x...",
  "readinessOnly": true
}

Full prepare returns unsignedTransactions, signingMode, instructions, and requestId. Sign and broadcast from your wallet, then:

Tool: get_transaction_status

{ "txHash": "0x..." }

Write workflow​

check_*_readiness (optional) → prepare_* → sign → broadcast → get_transaction_status

See MCP write workflow and Subscribe workflow.