API

Every IncidentFlow MCP response — over MCP tool calls and over HTTP — uses one canonical envelope and one error model, versioned so a client written against v1 stays compatible as the platform evolves.

Base URL

All endpoints are served from https://mcp.incidentflow.io.

Authentication

The /mcp endpoint requires a Bearer token; the version and schema endpoints below are public (they expose no secrets).

• OAuth 2.1 (recommended) — IncidentFlow MCP is an OAuth resource server. Clients discover the authorization server via /.well-known/oauth-protected-resource and obtain a workspace‑scoped RS256 access token. Scopes: mcp:read, mcp:tools:run.
• Personal Access Token — send Authorization: Bearer <pat> directly.

Tokens are always workspace‑scoped. Send tokens in the Authorization header only — never as a query parameter.

Version axes

Three independent versions are reported and never conflated:

Version	Example	Meaning
service_version	1.0.55	The specific server build (informational).
api_version	v1	The API surface. Present in every envelope.
schema_version	1.0	The response structure (envelope + data schemas).

The MCP protocol version is negotiated by the MCP framework and is separate from all three.

Response envelope

Every successful response is an object with exactly these eight keys:

{
  "api_version": "v1",
  "schema_version": "1.0",
  "schema_id": "incidentflow.mcp-version.response",
  "status": "success",
  "request_id": "req_9f2c…",
  "data": { "…": "tool-specific payload" },
  "error": null,
  "meta": { "generated_at": "…", "truncated": false, "warnings": [] }
}

Field	Description
api_version	API surface version (v1).
schema_version	Structure version (1.0).
schema_id	Stable id of the schema this response validates against.
status	success or error.
request_id	Correlation id, echoed in the X-Request-ID header.
data	Tool‑specific payload on success; null on error.
error	null on success; the error object below on error.
meta	generated_at, truncated, and warnings[].

Error model

On failure, status is "error", data is null, and error is:

{
  "code": "INVALID_ARGUMENT",
  "message": "Invalid job_id format",
  "retryable": false,
  "details": { "field": "job_id", "expected": "uuid" }
}

Errors use one of ten canonical codes:

Code	Meaning	Retryable
INVALID_ARGUMENT	Malformed or missing input.	no
UNAUTHENTICATED	Missing or invalid credentials.	no
PERMISSION_DENIED	Authenticated but not allowed.	no
NOT_FOUND	Target does not exist.	no
CONFLICT	State conflict.	no
RATE_LIMITED	Too many requests.	yes
INTEGRATION_UNAVAILABLE	A required integration is not connected/reachable.	yes
UPSTREAM_ERROR	An upstream dependency failed.	yes
TIMEOUT	The operation timed out.	yes
INTERNAL_ERROR	Unexpected server error.	yes

Over MCP, tool errors also set isError: true on the tool result, with the same canonical code.

Public endpoints

Unauthenticated, no secrets. All three return caching + version‑mirror headers.

GET /version

Service, API, and contract versions plus supported and deprecated versions.

{
  "service": "incidentflow-mcp",
  "service_version": "1.0.55",
  "api_version": "v1",
  "contract_version": "1.0",
  "supported_api_versions": ["v1"],
  "supported_schema_versions": ["1.0"],
  "deprecated_api_versions": [],
  "environment": "production"
}

GET /schemas

Catalog of published JSON Schemas (envelope, error, and per‑tool responses).

{ "api_version": "v1", "schema_version": "1.0", "schemas": [ /* … */ ] }

GET /schemas/{schema_id}

One generated Draft 2020‑12 JSON Schema. Returns 200 when known and 404 when unknown. Schema ids are stable and namespaced, e.g. incidentflow.mcp-version.response, incidentflow.common.error.

Response headers

GET /version and /schemas* return:

Content-Type: application/json
Cache-Control: no-cache
ETag: "<content-hash>"
X-IncidentFlow-API-Version: v1
X-IncidentFlow-Schema-Version: 1.0
X-Request-ID: <request-id>

A matching If-None-Match yields 304 Not Modified. The JSON body remains the primary source of contract metadata; headers are a convenience mirror.

Health

• GET /healthz — liveness. GET /readyz — readiness. Both public.

The MCP endpoint

GET|POST /mcp — the MCP Streamable HTTP transport (stateless). Requires a Bearer token; unauthenticated requests receive 401 with a WWW-Authenticate: Bearer resource_metadata="…" challenge pointing at the OAuth discovery document. Call tools via standard MCP tools/call requests; the tool result's structuredContent is the envelope described above.

Compatibility

• New optional data fields are additive and bump schema_version minor (1.0 → 1.1); clients must ignore unknown fields.
• Removing or renaming a field bumps schema_version major and follows a deprecation window.
• A new api_version is served alongside the old one until its sunset date; deprecations are announced in mcp_version.deprecated_api_versions.