CoreStory MCP Protocol API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation MCP Protocol API
  description: '# CoreStory API Overview


    The CoreStory API provides programmatic access to structured insights derived from software source code.'
  version: 1.26.2
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: MCP Protocol
paths:
  /mcp/:
    get:
      tags:
      - MCP Protocol
      summary: MCP SSE stream
      description: 'MCP SSE (Server-Sent Events) Stream Endpoint


        Opens an SSE stream for server-to-client communication.

        MCP Spec Requirement: GET /mcp MUST return either:

        - text/event-stream (SSE) for streaming server notifications, OR

        - HTTP 405 Method Not Allowed


        This implementation returns SSE for spec compliance.'
      operationId: mcp_sse_stream
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /mcp/{org}:
    get:
      tags:
      - MCP Protocol
      summary: MCP SSE stream (per-org)
      description: 'Per-org SSE stream — the ``GET`` counterpart of ``POST /mcp/{org}``.


        The org segment pins the organization for the JSON-RPC ``POST``; the GET

        stream itself only carries server notifications, so it behaves identically

        to the bare ``GET /mcp`` stream.'
      operationId: mcp_sse_stream_for_org
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
          title: Org
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    post:
      tags:
      - MCP Protocol
      summary: MCP JSON-RPC endpoint (per-org)
      description: 'Per-org MCP JSON-RPC endpoint.


        The ``{org}`` path segment (a Clerk org id or slug) pins which organization a

        Clerk OAuth/session request acts under, taking precedence over the

        ``X-Corestory-Org`` header and the token''s ``org_id``. Non-membership is a 403

        authorization decision inside ``resolve_mcp_auth``, which the MCP surface

        surfaces as a JSON-RPC error over HTTP 200 (not a literal HTTP 403). On the

        ``csk_`` API-key path the org is fixed by the key, so the segment is ignored

        there.'
      operationId: mcp_jsonrpc_for_org
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
          title: Org
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /mcp:
    post:
      tags:
      - MCP Protocol
      summary: MCP JSON-RPC endpoint
      description: 'Bare MCP JSON-RPC endpoint.


        The acting organization is resolved from the request: an ``X-Corestory-Org``

        header, a session token''s ``org_id``, or membership-based auto-resolution.

        Use ``POST /mcp/{org}`` to pin it via the URL instead.'
      operationId: mcp_jsonrpc
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ErrorBody:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Optional extra context for the error.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter the Bearer token from Clerk authentication
x-tagGroups:
- name: Ingest Your Codebase
  tags:
  - vector_store
  - projects
  - pre_ingestion
  - reingestion
- name: Generate Code Intelligence
  tags:
  - documents
  - document_generation
  - document_formatters
  - prd
  - prd_version
  - tech_spec
  - quality_metrics
  - sample_projects
- name: Query Your Codebase
  tags:
  - conversations
  - workflows
  - discovery
  - context
  - artifacts
- name: Manage and Inspect Intelligence
  tags:
  - api_debugging
  - events
  - version
  - files
  - cache
  - token_tracking
- name: Authenticate and Manage Access
  tags:
  - clerk_authentication
  - github_webhooks
  - github_integration
  - organizations
  - api_key_management
  - mcp_token_management
  - user
- name: (Advanced) Prompt Tuning
  tags:
  - prompts
- name: MCP Protocol
  tags:
  - mcp_protocol
- name: Administration
  tags:
  - admin