API Specifications — MCP Tools
8 tools in the API Specifications group of the Routebase MCP server.
create_spec
Create a new API specification in the active project. Returns the id of the automatically created initial draft version — use it as versionId when creating endpoints. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Name of the API specification |
version |
string | Yes | Version string (e.g., '1.0.0') |
openApiVersion |
string | No (default "v3_1") |
OpenAPI version: 'v3_0' or 'v3_1' (default 'v3_1') |
description |
string | No | Optional description of the API |
delete_spec
Delete an API specification and everything under it — versions, endpoints, schemas, folders and tags. Requires project context.
Required scope: specs:delete
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification to delete |
export_spec
Export an API specification as OpenAPI YAML, JSON, or Postman Collection. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification to export |
format |
string | No (default "yaml") |
Export format: 'yaml' (default), 'json', or 'postman' |
get_spec
Get detailed information about an API specification, including whether its documentation is internal, authenticated or public and under which slug. Includes the spec's versions (newest first, up to 10) — use their id as versionId for create_endpoint and other version-scoped tools. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
import_spec
Import an OpenAPI specification from YAML or JSON content into the active project. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
content |
string | Yes | The OpenAPI specification content (YAML or JSON string) |
format |
string | No | Format hint: 'yaml', 'json', or omit for auto-detection |
validateOnly |
boolean | No (default false) |
If true, only validate without importing (default false) |
convertToOpenApi31 |
boolean | No (default false) |
Convert OpenAPI 3.0 to 3.1 during import (default false) |
createFoldersFromTags |
boolean | No (default false) |
Create folders from OpenAPI tags (default false) |
shortenSchemaNames |
boolean | No (default false) |
Shorten schema names to the last dot-segment when unique within the spec (default false) |
discardOriginalSchemaNames |
boolean | No (default false) |
With shortenSchemaNames: permanently discard the cut namespace segments — original names are not stored; re-imports/diffs against the source file will report renames (default false) |
list_specs
List all API specifications in the active project. Set scope to 'org' to list the published APIs across every project in the organization instead — each entry carries the projectId and specId to pass to set_context. Requires project context for scope 'project'.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
skip |
integer | No (default 0) |
Number of specs to skip (for pagination, default 0) |
take |
integer | No (default 50) |
Number of specs to return (default 50, max 100) |
scope |
string | No (default "project") |
What to list: 'project' (default) or 'org' |
update_spec
Update an API specification's metadata: name, version string, description, base path or server URL. Omit a field to keep its current value; pass an empty string to clear description, basePath or serverUrl (name and version cannot be empty). Get the spec's rowVersion from get_spec. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
rowVersion |
string | Yes | Base64-encoded row version of the spec (for concurrency control), from get_spec |
name |
string | No | New name, or omit to keep the current name |
version |
string | No | New version string (e.g. '2.0.0'), or omit to keep the current one |
description |
string | No | New description; empty string clears it, omit to keep the current one |
basePath |
string | No | New base path (e.g. '/v2'); empty string clears it, omit to keep the current one |
serverUrl |
string | No | New server URL (absolute HTTPS); empty string clears it, omit to keep the current one |
validate_spec
Validate an OpenAPI specification against the standard. Provide either content to validate directly, or specId to validate an existing spec. Set mode to 'import' for a dry run of import_spec instead: same errors and warnings, plus what would be created (endpoint, schema and folder counts), the detected format and whether a 3.0 → 3.1 conversion happened. Nothing is written either way.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
content |
string | No | The OpenAPI specification content to validate (YAML or JSON). Provide either content or specId, not both. |
specId |
string | No | Public ID (GUID) of an existing spec to validate. If provided, the spec is exported first and then validated. |
format |
string | No | Format hint: 'yaml', 'json', or omit for auto-detection |
mode |
string | No (default "openapi") |
What to check: 'openapi' (default) or 'import' |
convertToOpenApi31 |
boolean | No (default false) |
For mode 'import': convert a 3.0 document to 3.1 (default false) |
shortenSchemaNames |
boolean | No (default false) |
For mode 'import': shorten generated schema names (default false) |