AlertCamp MCP API

openapi: 3.2.0
info:
  title: AlertCamp MCP API
  description: Service d'alertes de disponibilité SEPAQ pour le camping au Québec
  version: 0.1.0
tags:
- name: MCP
paths:
  /api/v1/agents/fund:
    post:
      tags:
      - MCP
      summary: Fund Agent
      description: Quote, or accept payment and fund a principal.
      operationId: fund_agent_api_v1_agents_fund_post
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment-Signature
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /mcp:
    get:
      tags:
      - MCP
      summary: Mcp Get Not Allowed
      description: 405 for GET — this revision is POST-only (no SSE stream to resume).
      operationId: mcp_get_not_allowed_mcp_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
      - MCP
      summary: Mcp Endpoint
      description: 'The single MCP endpoint (2026-07-28 Streamable HTTP, JSON mode).


        Authenticated by an audience-bound MCP token (preferred) or a Firebase

        ID token (so the app keeps working). Either way the agent acts as its

        owner and inherits that user''s tier and quotas unchanged — nothing new

        is sold, which is what keeps this clear of the app stores''

        in-app-purchase rules.


        Auth is resolved in the body rather than through ``Depends`` because an

        unauthenticated call must answer with the ``WWW-Authenticate`` challenge

        above, not FastAPI''s bare 401.'
      operationId: mcp_endpoint_mcp_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    delete:
      tags:
      - MCP
      summary: Mcp Delete Not Allowed
      description: 405 for DELETE — there is no session to terminate.
      operationId: mcp_delete_not_allowed_mcp_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/v1/auth/mcp-tokens:
    post:
      tags:
      - MCP
      summary: Create Mcp Token
      description: Mint a credential for one agent.
      operationId: create_mcp_token_api_v1_auth_mcp_tokens_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPTokenCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPTokenCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - MCP
      summary: List Mcp Tokens
      description: 'Every credential this user has issued, revoked ones included.


        Revoked rows are kept and returned: "I revoked that last week" is the

        question a user actually has, and hiding the row makes it unanswerable.'
      operationId: list_mcp_tokens_api_v1_auth_mcp_tokens_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MCPTokenInfo'
                title: Response List Mcp Tokens Api V1 Auth Mcp Tokens Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/mcp-tokens/{jti}:
    delete:
      tags:
      - MCP
      summary: Revoke Mcp Token
      description: 'Withdraw one credential. Takes effect on the next request.


        Scoped to the caller''s own tokens — the 404 for someone else''s is

        deliberate: confirming a jti exists would leak that it does.'
      operationId: revoke_mcp_token_api_v1_auth_mcp_tokens__jti__delete
      parameters:
      - name: jti
        in: path
        required: true
        schema:
          type: string
          title: Jti
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/oauth-protected-resource/{resource_path}:
    get:
      tags:
      - MCP
      summary: Protected Resource Metadata
      description: 'Tell a client where credentials for this resource come from.


        Required of an MCP server by the 2026-07-28 spec. ``resource`` is the

        canonical identifier a token''s ``aud`` must equal — publishing it is

        what lets a client ask its authorization server for a token scoped to

        US rather than one that would work anywhere.


        ``authorization_servers`` lists this service: AlertCamp issues its own

        MCP tokens today (see ``services/mcp_tokens.py``). When the full

        OAuth 2.1 authorization-code + CIMD flow lands (plan §6.3 step 2) the

        entry stays the same — only the flow behind it changes.'
      operationId: protected_resource_metadata__well_known_oauth_protected_resource__resource_path__get
      parameters:
      - name: resource_path
        in: path
        required: true
        schema:
          type: string
          title: Resource Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - MCP
      summary: Protected Resource Metadata
      description: 'Tell a client where credentials for this resource come from.


        Required of an MCP server by the 2026-07-28 spec. ``resource`` is the

        canonical identifier a token''s ``aud`` must equal — publishing it is

        what lets a client ask its authorization server for a token scoped to

        US rather than one that would work anywhere.


        ``authorization_servers`` lists this service: AlertCamp issues its own

        MCP tokens today (see ``services/mcp_tokens.py``). When the full

        OAuth 2.1 authorization-code + CIMD flow lands (plan §6.3 step 2) the

        entry stays the same — only the flow behind it changes.'
      operationId: protected_resource_metadata__well_known_oauth_protected_resource_get
      parameters:
      - name: resource_path
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Resource Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/openai-apps-challenge:
    get:
      tags:
      - MCP
      summary: Openai Apps Challenge
      description: 'Prove we control this host, for the ChatGPT app directory.


        The token is served verbatim as plain text — OpenAI compares bytes, so

        a JSON wrapper or a trailing newline is a failed verification with no

        useful error.


        Unset answers **404**, not an empty 200. A blank body that matches

        nothing reads as "verification failed, cause unknown"; a 404 says

        plainly that no challenge is configured on this deploy.


        Never cached: a stale token outlives the submission it belonged to,

        and re-verification would then compare against a value we have since

        rotated.'
      operationId: openai_apps_challenge__well_known_openai_apps_challenge_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-authorization-server/{issuer_path}:
    get:
      tags:
      - MCP
      summary: Authorization Server Metadata
      description: 'What this server supports, so a client need not be told out of band.


        Also answered at the RFC 8414 path-scoped location for the resource''s

        path: a client that treats the resource URL as the issuer asks for

        ``/.well-known/oauth-authorization-server/mcp``, and some stop at a 404

        rather than retrying the root form.'
      operationId: authorization_server_metadata__well_known_oauth_authorization_server__issuer_path__get
      parameters:
      - name: issuer_path
        in: path
        required: true
        schema:
          type: string
          title: Issuer Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - MCP
      summary: Authorization Server Metadata
      description: 'What this server supports, so a client need not be told out of band.


        Also answered at the RFC 8414 path-scoped location for the resource''s

        path: a client that treats the resource URL as the issuer asks for

        ``/.well-known/oauth-authorization-server/mcp``, and some stop at a 404

        rather than retrying the root form.'
      operationId: authorization_server_metadata__well_known_oauth_authorization_server_get
      parameters:
      - name: issuer_path
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Issuer Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/register:
    post:
      tags:
      - MCP
      summary: Register
      description: 'Register a client that cannot present a metadata document.


        Open to anyone, which is the point and the risk: nothing in the body is

        verified, so the user is later shown the redirect host, not the name.'
      operationId: register_oauth_register_post
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/clients/{name}.json:
    get:
      tags:
      - MCP
      summary: Hosted Client Metadata
      description: A client_id we issued — see ``HOSTED_CLIENTS`` in services/cimd.py.
      operationId: hosted_client_metadata_oauth_clients__name__json_get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/authorize:
    get:
      tags:
      - MCP
      summary: Authorize Form
      description: Record the request and show its code.
      operationId: authorize_form_oauth_authorize_get
      parameters:
      - name: client_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
      - name: redirect_uri
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Uri
      - name: response_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Response Type
      - name: scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Scope
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      - name: code_challenge
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge
      - name: code_challenge_method
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge Method
      - name: resource
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/pending/{pending_id}:
    get:
      tags:
      - MCP
      summary: Poll Pending
      description: 'Where the waiting browser learns the outcome.


        Keyed on the long random ``id``, never the short user_code: polling is

        unauthenticated, so the handle it accepts must not be one a person

        could guess from across the room.'
      operationId: poll_pending_oauth_pending__pending_id__get
      parameters:
      - name: pending_id
        in: path
        required: true
        schema:
          type: string
          title: Pending Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/token:
    post:
      tags:
      - MCP
      summary: Token Endpoint
      description: Exchange an authorization code for an MCP access token.
      operationId: token_endpoint_oauth_token_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - $ref: '#/components/schemas/Body_token_endpoint_oauth_token_post'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/oauth-requests:
    get:
      tags:
      - MCP
      summary: Lookup Pending
      description: 'Resolve a code so the app can show WHAT is being approved.


        A 404 covers unknown, expired and already-answered alike — telling them

        apart would let someone probe the code space for live requests.'
      operationId: lookup_pending_api_v1_auth_oauth_requests_get
      parameters:
      - name: user_code
        in: query
        required: true
        schema:
          type: string
          title: User Code
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingRequestInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/oauth-requests/approve:
    post:
      tags:
      - MCP
      summary: Approve Pending
      description: Grant the agent access, as this user.
      operationId: approve_pending_api_v1_auth_oauth_requests_approve_post
      parameters:
      - name: user_code
        in: query
        required: true
        schema:
          type: string
          title: User Code
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/oauth-requests/deny:
    post:
      tags:
      - MCP
      summary: Deny Pending
      description: Refuse it, so the waiting page stops rather than timing out.
      operationId: deny_pending_api_v1_auth_oauth_requests_deny_post
      parameters:
      - name: user_code
        in: query
        required: true
        schema:
          type: string
          title: User Code
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FundRequest:
      properties:
        watch_days:
          type: integer
          minimum: 1.0
          title: Watch Days
          description: 'How many days of monitoring to buy. The billed unit is a WATCH-DAY, not a request: one cheap call here commits us to polling for that long. Already funded and only need a fresh token? Send 1 — funding extends, so you keep the days you have and the token covers all of them.'
      type: object
      required:
      - watch_days
      title: FundRequest
    MCPTokenCreate:
      properties:
        name:
          type: string
          maxLength: 100
          title: Name
          default: ''
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
          description: 'Subset of alerts:read / alerts:write. Default: both.'
      type: object
      title: MCPTokenCreate
    MCPTokenCreated:
      properties:
        jti:
          type: string
          title: Jti
        name:
          type: string
          title: Name
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
          description: The client's CIMD URL, for a token minted through the OAuth flow. `name` is the client's own claim about itself; this is the part that was verified.
        scopes:
          items:
            type: string
          type: array
          title: Scopes
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        last_used_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used At
        revoked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Revoked At
        token:
          type: string
          title: Token
          description: Shown ONCE. Nothing recoverable is stored, so a lost token is re-minted rather than retrieved.
      type: object
      required:
      - jti
      - name
      - scopes
      - created_at
      - expires_at
      - last_used_at
      - revoked_at
      - token
      title: MCPTokenCreated
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MCPTokenInfo:
      properties:
        jti:
          type: string
          title: Jti
        name:
          type: string
          title: Name
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
          description: The client's CIMD URL, for a token minted through the OAuth flow. `name` is the client's own claim about itself; this is the part that was verified.
        scopes:
          items:
            type: string
          type: array
          title: Scopes
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        last_used_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used At
        revoked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Revoked At
      type: object
      required:
      - jti
      - name
      - scopes
      - created_at
      - expires_at
      - last_used_at
      - revoked_at
      title: MCPTokenInfo
      description: 'A token''s record. Never carries the token itself — it is

        unrecoverable after issue, by design.'
    PendingRequestInfo:
      properties:
        user_code:
          type: string
          title: User Code
        client_name:
          type: string
          title: Client Name
          description: From the client's own metadata document — display it as an untrusted claim, not as a verified identity.
        client_id:
          type: string
          title: Client Id
        scopes:
          items:
            type: string
          type: array
          title: Scopes
      type: object
      required:
      - user_code
      - client_name
      - client_id
      - scopes
      title: PendingRequestInfo
      description: What the app shows before asking "approve?".
    ApprovalResult:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: ApprovalResult
    Body_token_endpoint_oauth_token_post:
      properties:
        grant_type:
          type: string
          title: Grant Type
          default: ''
        code:
          type: string
          title: Code
          default: ''
        redirect_uri:
          type: string
          title: Redirect Uri
          default: ''
        client_id:
          type: string
          title: Client Id
          default: ''
        client_secret:
          type: string
          title: Client Secret
          default: ''
        code_verifier:
          type: string
          title: Code Verifier
          default: ''
        resource:
          type: string
          title: Resource
          default: ''
      type: object
      title: Body_token_endpoint_oauth_token_post