Schemas — MCP Tools

7 tools in the Schemas group of the Routebase MCP server.

create_schema

Create a new reusable schema in an API specification. The schema can then be referenced by endpoints, request bodies, and responses. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version to add the schema to
name	string	Yes	Schema name (e.g., 'User', 'ErrorResponse', 'PaginatedList')
jsonSchema	string	Yes	JSON Schema definition as a string (e.g., '{"type":"object","properties":{...}}')
description	string	No	Description of the schema

delete_schema

Delete a schema (soft delete). This does NOT check references — a schema still used by endpoints, request bodies or responses is deleted anyway, and every one of them becomes a review item. Call get_schema with includeUsage first and clear the references you do not want to break. Requires project context.

Required scope: specs:delete

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version
schemaId	string	Yes	Public ID (GUID) of the schema to delete

get_schema

Get detailed information about a schema including its full JSON Schema definition. Optionally include usage details showing which endpoints reference it. Requires project context.

Required scope: specs:read

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
schemaId	string	Yes	Public ID (GUID) of the schema
includeUsage	boolean	No (default false)	Include usage details showing which endpoints reference this schema (default false)

list_schemas

List all schemas of an API specification. Optionally include usage counts showing how many endpoints reference each schema. Set scope to 'project' to look across every spec in the project instead — that returns the groups of structurally identical schemas (candidates for the shared library) plus counts, not the full list, and specId is then ignored. Requires project context.

Required scope: specs:read

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	No	Optional version ID (GUID) to filter schemas by a specific version
includeUsageCounts	boolean	No (default false)	Include usage counts per schema (default false, slightly slower)
scope	string	No (default "spec")	What to look at: 'spec' (default) or 'project'

migrate_schema_links

Find inline request bodies, responses and parameters across a spec that match an existing reusable component and link them to it, so the shape lives in one place. ALWAYS run with dryRun first and read the report — the matching is similarity-based, and a run with dryRun false rewrites every match it found. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
dryRun	boolean	No (default true)	Report what would change without writing anything (default true). Set false only after reviewing a dry run.
minimumSimilarity	number	No (default 0.9)	How close a match has to be, 0.0–1.0 (default 0.9). Lower values link more aggressively and are more likely to link things that only look alike.

restore_schema

Restore a soft-deleted schema into its version. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version the schema belongs to
schemaId	string	Yes	Public ID (GUID) of the deleted schema

update_schema

Update an existing schema. Requires the rowVersion from get_schema for optimistic concurrency control (Base64-encoded string). Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version
schemaId	string	Yes	Public ID (GUID) of the schema to update
name	string	Yes	Schema name
jsonSchema	string	Yes	JSON Schema definition as a string
rowVersion	string	Yes	Base64-encoded row version from get_schema (for concurrency control)
description	string	No	Description of the schema