ClawLink MCP API

openapi: 3.2.0
info:
  title: ClawLink Agent MCP API
  version: 1.0.0
  summary: Tool discovery and execution for AI agents
  description: 'ClawLink connects AI agents to 100+ external apps (Gmail, Slack, Notion, GitHub, and more) through one hosted account. This document describes the agent-facing surface: tool discovery, tool execution, the MCP endpoint, and the two credential registration flows. How authentication works, including the human-approval requirement, is documented at https://claw-link.dev/auth.md. All other routes on claw-link.dev (dashboard, billing, connect pages) are browser-facing and not part of this API.'
  contact:
    name: ClawLink
    url: https://claw-link.dev
servers:
- url: https://claw-link.dev
security:
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: MCP
  description: Model Context Protocol endpoint (JSON-RPC 2.0)
paths:
  /api/mcp:
    get:
      tags:
      - MCP
      operationId: describeMcpSurface
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      - OAuth2:
        - openid
      summary: Describe the MCP surface
      description: Returns the tool, prompt, and resource listing of the MCP server without a JSON-RPC handshake.
      responses:
        '200':
          description: MCP surface description
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  transport:
                    type: string
                  endpoint:
                    type: string
                  tools:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  prompts:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  resources:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - MCP
      operationId: mcpJsonRpc
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      - OAuth2:
        - openid
      summary: MCP JSON-RPC 2.0 endpoint
      description: 'Model Context Protocol over plain JSON-RPC 2.0 request/response (no SSE stream). Supports initialize, tools/list, and tools/call. The server exposes 10 tools namespaced clawlink.* covering discovery (clawlink.search, clawlink.list_actions, clawlink.get_action), connections (clawlink.list_integrations, clawlink.get_connection, clawlink.connect_app), and execution (clawlink.execute, clawlink.get_execution). Write tools need "confirm": true in clawlink.execute arguments.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  const: '2.0'
                id:
                  type:
                  - integer
                  - string
                  - 'null'
                method:
                  type: string
                  examples:
                  - initialize
                  - tools/list
                  - tools/call
                params:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: JSON-RPC 2.0 response (errors are carried in the JSON-RPC "error" member)
          content:
            application/json:
              schema:
                type: object
                required:
                - jsonrpc
                properties:
                  jsonrpc:
                    const: '2.0'
                  id:
                    type:
                    - integer
                    - string
                    - 'null'
                  result:
                    type: object
                    additionalProperties: true
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-clawlink-api-key
      description: A cllk_live_ API key obtained through one of the registration flows.
    BearerAuth:
      type: http
      scheme: bearer
      description: The same cllk_live_ key as a bearer token. Both header forms are accepted on every authenticated endpoint.
    OAuth2:
      type: oauth2
      description: For remote MCP clients calling /api/mcp. Discovery starts at https://claw-link.dev/.well-known/oauth-protected-resource; client registration follows the authorization server metadata.
      flows:
        authorizationCode:
          authorizationUrl: https://clerk.claw-link.dev/oauth/authorize
          tokenUrl: https://clerk.claw-link.dev/oauth/token
          refreshUrl: https://clerk.claw-link.dev/oauth/token
          scopes:
            openid: Identify the authorizing user
            email: Read the user's email address
            profile: Read basic profile information
externalDocs:
  description: ClawLink documentation
  url: https://docs.claw-link.dev