MCP tools
The Apiome catalog server registers 14 tools. Call them with tools/call over stdio or streamable HTTP (/mcp); see the MCP quick-start to connect a host.
| Tool | Summary |
|---|---|
ping | Smoke-test: service name, package version, Postgres reachability, UTC timestamp. |
project.list | List distinct projects (tenant + project) that have at least one published spec revision the caller can see. |
spec.describe | Return metadata for a single published OpenAPI spec revision by id (UUID). |
spec.describe_component | Return one OpenAPI component definition for a published spec revision by id (UUID): kind is schemas, parameters, responses, or securitySchemes (same grouping as spec.list_components); name is the component key in that section. |
spec.describe_operation | Return OpenAPI fragments for one HTTP operation on a published spec revision: parameters (path-item + operation merge, operation wins same name/in), requestBody, responses, and security (operation override or document default). |
spec.export_yaml | Return the generated OpenAPI 3.1 document as YAML text for a published spec revision by id (UUID). |
spec.get_openapi | Return the generated OpenAPI 3.1 document (JSON object) for a published spec revision by id (UUID). |
spec.list | List published OpenAPI specs with cursor pagination. |
spec.list_components | Return OpenAPI component names for a published spec revision by id (UUID), grouped by kind: schemas, parameters, responses, securitySchemes. |
spec.list_my_specs | List OpenAPI spec revisions this MCP API key can read: in-scope public catalog rows (apiome.mcp_v_public_specs) plus in-scope private published revisions for the key's tenant (same rules as spec.list when authenticated). |
spec.list_operations | Return a compact index of HTTP operations for a published spec revision by id (UUID): each item has path, method, operation_id, summary, and tags. |
spec.list_tags | Distinct version-tag names across published public OpenAPI specs with counts of specs that expose each tag (via apiome.mcp_v_public_specs). |
spec.search | Search published public OpenAPI specs with Postgres full-text search (english config) over project title, revision description, version label, and tag names (maintained in apiome.versions.mcp_public_doc_tsv). |
spec.search_semantic | Semantic search over published public specs that have mcp_public_embedding populated (pgvector cosine distance vs OpenAI-compatible query embeddings). |
ping
Smoke-test: service name, package version, Postgres reachability, UTC timestamp.
Arguments:
Takes no arguments.
Returns: object.
project.list
List distinct projects (tenant + project) that have at least one published spec revision the caller can see. Anonymous: derived from the public catalog (apiome.mcp_v_public_specs). With Authorization: Bearer <MCP API key>, merges in-scope public rows plus in-scope private published revisions for the key's tenant (same scope rules as spec.list). Each item: tenant_id, project_id, title, updated_at (UTC Z; latest revision activity in scope). Optional filters: tenant_id, project_id (UUID strings). limit defaults to 50, capped at 100. Pass next_cursor from the previous response for the next page.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
tenant_id | string or null | no | null | |
project_id | string or null | no | null | |
limit | integer or null | no | null | |
cursor | string or null | no | null |
Returns: object.
spec.describe
Return metadata for a single published OpenAPI spec revision by id (UUID). Fields: id, title, version, description, owner (tenant slug), tags, updated_at (UTC Z). Anonymous callers see public revisions only (apiome.mcp_v_public_specs). With Authorization: Bearer <MCP API key> (or stdio meta credentials), in-scope private published revisions for the key's tenant are included (#3012). Raises not-found when the revision is missing, out of scope, or not accessible.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes |
Returns: object.
spec.describe_component
Return one OpenAPI component definition for a published spec revision by id (UUID): kind is schemas, parameters, responses, or securitySchemes (same grouping as spec.list_components); name is the component key in that section. Internal #/… $ref values are expanded; external refs are left as-is. Same visibility and auth rules as spec.get_openapi (#3021). Raises not-found for inaccessible revisions or unknown kind/name.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes | ||
kind | string | yes | ||
name | string | yes |
Returns: unstructured content (no output schema).
spec.describe_operation
Return OpenAPI fragments for one HTTP operation on a published spec revision: parameters (path-item + operation merge, operation wins same name/in), requestBody, responses, and security (operation override or document default). Internal #/… $ref values are expanded; external refs are left as-is. Same visibility and auth rules as spec.get_openapi (#3019). Raises not-found for inaccessible revisions or unknown path/method.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes | ||
path | string | yes | ||
method | string | yes |
Returns: object.
spec.export_yaml
Return the generated OpenAPI 3.1 document as YAML text for a published spec revision by id (UUID). Same semantics as spec.get_openapi: anonymous callers see public revisions only; with Authorization: Bearer <MCP API key>, in-scope private published revisions are included (#3017). Response field openapi_yaml round-trips with YAML loaders to the same structure as the JSON tool. If UTF-8 YAML exceeds APIOME_MCP_OPENAPI_MAX_JSON_BYTES (default 2 MiB), returns an error analogous to HTTP 413.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes |
Returns: object.
spec.get_openapi
Return the generated OpenAPI 3.1 document (JSON object) for a published spec revision by id (UUID). Matches the REST schema export shape (paths, components.schemas, servers, securitySchemes). Anonymous callers: public revisions only. With Authorization: Bearer <MCP API key>, in-scope private published revisions for the tenant are included (#3016). Raises not-found when inaccessible. If the serialized document exceeds the configured byte cap (APIOME_MCP_OPENAPI_MAX_JSON_BYTES), returns an error analogous to HTTP 413.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes |
Returns: object.
spec.list
List published OpenAPI specs with cursor pagination. Anonymous callers see the public catalog (apiome.mcp_v_public_specs). With Authorization: Bearer <MCP API key> (or stdio meta credentials), results merge in-scope public rows plus in-scope private revisions for the key's tenant (#3011). Optional filters: tenant_id, project_id (UUID strings). limit defaults to 50, capped at 100. Pass next_cursor from the previous response for the next page.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
tenant_id | string or null | no | null | |
project_id | string or null | no | null | |
limit | integer or null | no | null | |
cursor | string or null | no | null |
Returns: object.
spec.list_components
Return OpenAPI component names for a published spec revision by id (UUID), grouped by kind: schemas, parameters, responses, securitySchemes. Each kind maps to a sorted list of component keys; kinds with no entries are omitted. Same visibility and auth rules as spec.get_openapi (#3020).
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes |
Returns: object.
spec.list_my_specs
List OpenAPI spec revisions this MCP API key can read: in-scope public catalog rows (apiome.mcp_v_public_specs) plus in-scope private published revisions for the key's tenant (same rules as spec.list when authenticated). Requires API key — anonymous calls are rejected. Response shape matches spec.list: items, has_more, next_cursor. Optional tenant_id / project_id (UUID strings). limit defaults to 50, capped at 100 (#3014).
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
tenant_id | string or null | no | null | |
project_id | string or null | no | null | |
limit | integer or null | no | null | |
cursor | string or null | no | null |
Returns: object.
spec.list_operations
Return a compact index of HTTP operations for a published spec revision by id (UUID): each item has path, method, operation_id, summary, and tags. Sorted by path then method. Same visibility and auth rules as spec.get_openapi: anonymous callers see public revisions only; with Authorization: Bearer <MCP API key>, in-scope private published revisions are included (#3018). Does not return the full OpenAPI document.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
spec_id | string | yes |
Returns: result — array of object.
spec.list_tags
Distinct version-tag names across published public OpenAPI specs with counts of specs that expose each tag (via apiome.mcp_v_public_specs). Sorted by count descending, then tag name ascending. Cursor pagination: limit defaults to 50, capped at 100; pass next_cursor from the previous response for the next page.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer or null | no | null | |
cursor | string or null | no | null |
Returns: object.
spec.search
Search published public OpenAPI specs with Postgres full-text search (english config) over project title, revision description, version label, and tag names (maintained in apiome.versions.mcp_public_doc_tsv). Required q must be non-empty after trimming and is passed to plainto_tsquery. Results use ts_rank_cd with cursor pagination: limit defaults to 50, capped at 100; pass next_cursor from the previous response for the next page.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | yes | ||
limit | integer or null | no | null | |
cursor | string or null | no | null |
Returns: object.
spec.search_semantic
Semantic search over published public specs that have mcp_public_embedding populated (pgvector cosine distance vs OpenAI-compatible query embeddings). Requires APIOME_MCP_OPENAI_API_KEY. Uses the same pagination shape as spec.search (items, has_more, next_cursor). Rows without embeddings are omitted until backfilled.
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | yes | ||
limit | integer or null | no | null | |
cursor | string or null | no | null |
Returns: object.
This page is generated from the server's registry; regenerate it with cd apiome-mcp && uv run python scripts/generate_mcp_reference_docs.py.