CatchIntent MCP API

openapi: 3.2.0
info:
  title: CatchIntent Agent Discovery MCP API
  version: 2.0.0
  description: Public discovery metadata for CatchIntent — the intent layer for B2B outbound. The executable API is the MCP Streamable HTTP endpoint at https://engine.catchintent.com/mcp. Tools cover LinkedIn-first agents, leads, outreach engagements, workspace usage, and brand/product context.
servers:
- url: https://engine.catchintent.com
  description: CatchIntent API and MCP origin
- url: https://catchintent.com
  description: CatchIntent marketing, documentation, and discovery origin
tags:
- name: MCP
  description: Model Context Protocol endpoint and related discovery metadata.
paths:
  /mcp:
    post:
      tags:
      - MCP
      operationId: callMcp
      summary: Call the CatchIntent MCP server
      description: Streamable HTTP MCP endpoint. Authenticate with OAuth 2.1 PKCE using the published authorization server metadata. Requests and responses are JSON-RPC messages defined by the Model Context Protocol.
      security:
      - mcpOAuth: []
      x-mcp:
        transport: streamable-http
        serverCard: https://catchintent.com/.well-known/mcp/server-card.json
        tools:
        - agent_list
        - agent_get
        - agent_create
        - agent_update
        - agent_set_status
        - agent_runs
        - lead_search
        - lead_get
        - lead_update_status
        - lead_enrich
        - lead_draft_outreach
        - lead_push_to_crm
        - engagement_list
        - engagement_get
        - engagement_enroll
        - engagement_reassign
        - engagement_pause
        - engagement_resume
        - engagement_mark_replied
        - engagement_exit
        - inbox_list
        - workspace_usage
        - workspace_icp_options
        - product_list
        - product_get
        - product_create
        - product_update
        - product_delete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              toolsList:
                summary: List available MCP tools
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: tools/list
                  params: {}
              toolsCall:
                summary: Call lead_search
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/call
                  params:
                    name: lead_search
                    arguments:
                      warmth:
                      - hot
                      - warm
                      page: 1
                      pageSize: 20
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '401':
          description: OAuth bearer token required. The WWW-Authenticate header includes protected resource metadata.
          headers:
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer challenge with resource_metadata pointing to OAuth protected resource metadata.
        '405':
          description: Only POST is supported for stateless Streamable HTTP MCP calls.
    get:
      tags:
      - MCP
      operationId: getMcpUnsupported
      summary: MCP SSE is not supported
      description: The CatchIntent MCP server is stateless and uses POST. GET returns 405.
    delete:
      tags:
      - MCP
      operationId: deleteMcpUnsupported
      summary: MCP session deletion is not supported
      description: The CatchIntent MCP server is stateless and does not support session deletion. DELETE returns 405.
components:
  schemas:
    JsonRpcResponse:
      type: object
      required:
      - jsonrpc
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: number
          - type: 'null'
        result:
          description: MCP result payload.
          type:
          - object
          - array
          - string
          - number
          - boolean
          - 'null'
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data: {}
          additionalProperties: true
      additionalProperties: true
    JsonRpcRequest:
      type: object
      required:
      - jsonrpc
      - id
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: number
          - type: 'null'
        method:
          type: string
          examples:
          - tools/list
          - tools/call
        params:
          type: object
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    mcpOAuth:
      type: oauth2
      description: OAuth 2.1 with PKCE. Discover endpoints from https://engine.catchintent.com/.well-known/oauth-authorization-server. Request only the scopes needed for the MCP tools being called.
      flows:
        authorizationCode:
          authorizationUrl: https://engine.catchintent.com/mcp/authorize
          tokenUrl: https://engine.catchintent.com/mcp/token
          scopes:
            read:agents: Read agents via agent_list, agent_get, agent_runs.
            write:agents: Create, update, and change status of agents via agent_create, agent_update, agent_set_status.
            read:leads: Read leads via lead_search, lead_get.
            write:leads: Update lead status, trigger enrichment, and draft outreach via lead_update_status, lead_enrich, lead_draft_outreach.
            read:outreach: Read outreach engagements and unified inbox via engagement_list, engagement_get, inbox_list.
            write:outreach: Manage engagement lifecycle via engagement_enroll, engagement_reassign, engagement_pause, engagement_resume, engagement_mark_replied, engagement_exit.
            read:workspace: Read workspace usage, ICP options, and product/brand context.
            write:workspace: Create, update, and delete products (brands).
            write:crm: Push qualified leads to connected CRMs via lead_push_to_crm.
x-mcp-tools:
  agent_list:
    scope: read:agents
    role: member
    description: List all agents in the workspace, filterable by productId or signalType.
  agent_get:
    scope: read:agents
    role: member
    description: 'Full details for one agent: status, targeting, signals, lead count, latest run.'
  agent_create:
    scope: write:agents
    role: admin
    planRequirement: Workspace agent limits apply.
    description: Create an agent with signals and targeting (icp, competitors, keywords, influencers).
  agent_update:
    scope: write:agents
    role: admin
    description: Partial update to an agent. Pass signals[] to replace the full signal set.
  agent_set_status:
    scope: write:agents
    role: admin
    description: Activate, pause, archive, unarchive, or start (immediate run for LinkedIn agents).
  agent_runs:
    scope: read:agents
    role: member
    description: Paginated run history per agent.
  lead_search:
    scope: read:leads
    role: member
    description: Search leads in the workspace. Filter by warmth, status, agent, source platform, or text.
  lead_get:
    scope: read:leads
    role: member
    description: 'Full lead details: profile, discovery context, warmth, status, source.'
  lead_update_status:
    scope: write:leads
    role: member
    description: Move a lead through the triage funnel. PUSHED is irreversible.
  lead_enrich:
    scope: write:leads
    role: member
    description: Trigger LinkedIn profile enrichment via Apify (idempotent).
  lead_draft_outreach:
    scope: write:leads
    role: member
    planRequirement: Workspace plan must have AI drafting enabled.
    description: Draft a personalised opener for a lead using discovery context and brand voice. Read-only — no send.
  lead_push_to_crm:
    scope: write:crm
    role: admin
    planRequirement: Workspace plan must include CRM and an integration must be connected.
    description: Push leads to HubSpot, Close, Pipedrive, or Zoho.
  engagement_list:
    scope: read:outreach
    role: member
    description: List outreach engagements. Filter by state or owner.
  engagement_get:
    scope: read:outreach
    role: member
    description: Full details for one engagement.
  engagement_enroll:
    scope: write:outreach
    role: member
    description: Enroll a lead into outreach. The current MCP user becomes the owner.
  engagement_reassign:
    scope: write:outreach
    role: admin
    description: Transfer an engagement to another workspace user.
  engagement_pause:
    scope: write:outreach
    role: member
    description: Pause an engagement, optionally until a date.
  engagement_resume:
    scope: write:outreach
    role: member
    description: Resume a paused engagement.
  engagement_mark_replied:
    scope: write:outreach
    role: member
    description: Mark REPLIED when the lead messaged back outside the product.
  engagement_exit:
    scope: write:outreach
    role: member
    description: 'Terminal exit. Reasons: meeting_booked, opt_out, manual, completed.'
  inbox_list:
    scope: read:outreach
    role: member
    description: Workspace-wide unified outreach inbox for one product.
  workspace_usage:
    scope: read:workspace
    role: member
    description: Current workspace usage vs plan limits.
  workspace_icp_options:
    scope: read:workspace
    role: member
    description: Valid options for ICP fields. Call before product_update or agent_create.
  product_list:
    scope: read:workspace
    role: member
    description: List every product/brand tracked by this workspace.
  product_get:
    scope: read:workspace
    role: member
    description: 'Full brand profile: name, description, domain, keywords, competitors, ICP, voice, offer.'
  product_create:
    scope: write:workspace
    role: admin
    planRequirement: Workspace product limits apply.
    description: Create a new product/brand.
  product_update:
    scope: write:workspace
    role: admin
    description: Update product fields. ICP labels resolved strictly to canonical IDs.
  product_delete:
    scope: write:workspace
    role: admin
    description: Delete a product if it is not the only one and no resources still reference it.