Endpoints — MCP Tools

Endpoints with parameters, request bodies, responses and security. This page documents the Endpoints group of the Routebase MCP server, with the scope and the parameters of each tool.

The group is part of the core set, so every session advertises it from the start.

add_parameter

Add a parameter to an endpoint (path, query, header, cookie, or querystring parameter). Use this to add one parameter; to change an existing one use update_parameter. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
name	string	Yes	Parameter name (e.g., 'id', 'page', 'Authorization')
location	string	Yes	Parameter location: 'path', 'query', 'header', 'cookie', or 'querystring' (3.2 specs only)
schemaType	string	Yes	Schema type: 'string', 'integer', 'number', 'boolean', 'array', 'object'
required	boolean	No (default false)	Whether the parameter is required (default false, path params are always required)
description	string	No	Description of the parameter
schemaFormat	string	No	Schema format (e.g., 'date-time', 'email', 'uuid', 'int32', 'int64')
example	string	No	Example value for the parameter. A bare value is fine ('us', '42'); JSON is accepted too.
defaultValue	string	No	Default value for the parameter
schemaId	string	No	Public ID (GUID) of a schema to link; when set, the parameter's schema is exported as a $ref to that component and schemaType is ignored on export.
style	string	No	OpenAPI style keyword ('form', 'deepObject', 'simple', 'cookie' (3.2), …); omit for the default
explode	boolean	No	OpenAPI explode; omit for the default
contentType	string	No	Querystring media type (default form-urlencoded)
serializedExample	string	No	3.2 only: example in wire form (serializedValue)

add_response

Add a response to an endpoint with status code, description, and optional schema. Provide either schemaJson (inline) or schemaId (reference), not both. Use this to add one response; to change an existing one use update_response. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
statusCode	integer	Yes	HTTP status code (e.g., 200, 201, 400, 404, 500)
description	string	No	Description of the response
contentType	string	No (default "application/json")	Response content type (default 'application/json')
schemaJson	string	No	Inline JSON Schema definition for the response body
example	string	No	Example response body
schemaId	string	No	Public ID (GUID) of an existing schema to reference (alternative to schemaJson)
itemSchemaJson	string	No	OpenAPI 3.2 only: JSON Schema of one item of a sequential media type (jsonl, json-seq, SSE)
mediaTypeComponentId	string	No	OpenAPI 3.2 only: id of a media type component the content entry references via $ref
serializedExample	string	No	3.2 only: example in wire form (serializedValue)

add_security_scheme

Assign a security scheme to one endpoint (endpointId) or to many at once (endpointIds plus versionId). The security scheme must already exist as a component in the spec. Pass either securitySchemeId or securitySchemeName (the OpenAPI component name, e.g. 'bearerAuth'). The multi-endpoint form is idempotent — endpoints that already carry the scheme are skipped. Use this to assign a scheme; to take an assignment off again use remove_endpoint_security_scheme. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	No	Public ID (GUID) of the endpoint — alternative to endpointIds
endpointIds	string	No	Comma-separated endpoint IDs (GUIDs) to assign in one call — alternative to endpointId; requires versionId
versionId	string	No	Public ID (GUID) of the spec version the endpoints belong to — required with endpointIds (from list_endpoints)
securitySchemeId	string	No	Public ID (GUID) of the security scheme component to assign — alternative to securitySchemeName
securitySchemeName	string	No	Name of the security scheme component (e.g. 'bearerAuth') — alternative to securitySchemeId
scopes	string	No	Comma-separated OAuth scopes (e.g., 'read:users,write:users')

bulk_update_endpoints

Act on many endpoints in one call. Actions: 'delete' removes them, 'move' puts them into a folder (omit folderId to move them to the root), 'reorder' sets their display order — for 'reorder' the endpointIds are the new order, so pass every endpoint you want ordered. Use this to act on many endpoints at once; for a single one use update_endpoint or delete_endpoint. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
action	string	Yes	What to do: 'delete', 'move' or 'reorder'
endpointIds	string	Yes	Endpoint IDs (GUIDs), comma-separated. For 'reorder' this is the new order.
folderId	string	No	Target folder ID (GUID) for 'move'; omit to move the endpoints to the root

create_endpoint

Create a new endpoint in an API specification. Requires a version ID because endpoints are version-scoped. Use this for one new endpoint; to bring in many at once from an existing document use import_spec. 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 endpoint to
path	string	Yes	Endpoint path (e.g., '/users/{id}', '/orders')
method	string	Yes	HTTP method: 'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'query'
summary	string	No	Short summary of what the endpoint does
description	string	No	Detailed description of the endpoint
operationId	string	No	Unique operation ID (e.g., 'getUser', 'createOrder')

delete_endpoint

Delete an endpoint (soft delete). Use this to remove one endpoint; to undo the delete later use restore_endpoint. 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
endpointId	string	Yes	Public ID (GUID) of the endpoint to delete

delete_parameter

Delete a parameter from an endpoint. Use this to remove a parameter; to change it instead use update_parameter. Requires project context.

Required scope: specs:delete

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
parameterId	string	Yes	Public ID (GUID) of the parameter to delete

delete_request_body

Remove an endpoint's request body entirely. To change it instead, use set_request_body; to only detach a linked component, use set_request_body with detachRequestBodyComponent. Requires project context.

Required scope: specs:delete

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint whose request body should be removed

delete_response

Delete a response from an endpoint. Use this to remove a response; to change it instead use update_response. Requires project context.

Required scope: specs:delete

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
responseId	string	Yes	Public ID (GUID) of the response to delete

get_endpoint

Get detailed information about an endpoint including parameters, request body, responses, and security schemes. Pass endpointIds instead of endpointId to fetch several at once (up to 25) — the same detail per endpoint, in one call. Use this when you already have the endpoint id; to browse a spec's endpoints or find an id use list_endpoints. Requires project context.

Required scope: specs:read

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	No	Public ID (GUID) of the endpoint — omit when using endpointIds
endpointIds	string	No	Public IDs (GUIDs) of several endpoints, comma-separated, at most 25

list_endpoints

List all endpoints of an API specification. Optionally filter by version. Set scope to 'project' to look across every spec in the project instead — that returns the groups of endpoints colliding on method and path (gateway routing conflicts) plus counts, not the full list, and specId is then ignored. Use this to browse endpoints or find an endpoint id; for one endpoint in full use get_endpoint. Requires project context (call set_context first).

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 endpoints by a specific version
skip	integer	No (default 0)	Number of endpoints to skip (for pagination, default 0)
take	integer	No (default 50)	Number of endpoints to return (default 50, max 100)
scope	string	No (default "spec")	What to look at: 'spec' (default) or 'project'

manage_response_header

Manage the headers a response declares. Actions: 'add' creates one on a response, 'update' replaces its fields, 'delete' removes it, 'link' points it at a reusable header component (the component then drives its shape), 'unlink' detaches it again and keeps the current values inline. 'add' and 'update' need name and schemaType; 'link' needs headerComponentId. Use this for the headers of one endpoint response; for reusable header components use manage_header_component. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
action	string	Yes	What to do: 'add', 'update', 'delete', 'link' or 'unlink'
endpointId	string	No	Public ID (GUID) of the endpoint — required for 'add', 'update' and 'delete'
responseId	string	No	Public ID (GUID) of the response — required for 'add', 'update' and 'delete'
responseHeaderId	string	No	Public ID (GUID) of the response header — required for everything but 'add'
name	string	No	Header name (e.g. 'X-Rate-Limit') — required for 'add' and 'update'
schemaType	string	No	Schema type: 'string', 'integer', 'number', 'boolean', 'array' or 'object' — required for 'add' and 'update'
required	boolean	No (default false)	Whether the header is always present (default false)
description	string	No	Optional description
schemaFormat	string	No	Optional schema format (e.g. 'date-time', 'int64')
example	string	No	Optional example value
headerComponentId	string	No	Public ID (GUID) of the header component — required for 'link', optional on 'add'
serializedExample	string	No	3.2 only: example in wire form (serializedValue)

move_endpoint_to_folder

Move an endpoint to a folder, or to root (ungrouped) by omitting folderId. Use this for one endpoint; to move many at once use bulk_update_endpoints with action 'move'. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint to move
folderId	string	No	Public ID (GUID) of the target folder, or omit to move to root (ungrouped)

remove_endpoint_security_scheme

Remove a security scheme assignment from an endpoint. The securitySchemeAssignmentId is the assignment's own public ID (from get_endpoint), not the security-scheme component ID. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
securitySchemeAssignmentId	string	Yes	Public ID (GUID) of the endpoint's security scheme assignment to remove (from get_endpoint)

restore_endpoint

Restore a soft-deleted endpoint into its version. Use this to bring a soft-deleted endpoint back; to remove one use delete_endpoint. 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 endpoint belongs to
endpointId	string	Yes	Public ID (GUID) of the deleted endpoint

set_request_body

Set or update the request body for an endpoint. Provide either schemaJson (inline JSON Schema) or schemaId (reference to an existing schema), not both. A fixture-backed example reference is always preserved as-is; the request body component link is preserved unless requestBodyComponentId names a different one or detachRequestBodyComponent is true. While a component is linked the exported spec emits a $ref to that component and ignores schemaJson/schemaId — detach it to make them take effect. Use this to set or change the body; to remove it entirely use delete_request_body. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
contentType	string	Yes	Content type (e.g., 'application/json', 'multipart/form-data')
required	boolean	No (default true)	Whether the request body is required (default true)
description	string	No	Description of the request body
schemaJson	string	No	Inline JSON Schema definition as a string
example	string	No	Example request body
schemaId	string	No	Public ID (GUID) of an existing schema to reference (alternative to schemaJson)
rowVersion	string	No	Base64-encoded row version (required when updating an existing request body)
requestBodyComponentId	string	No	Public ID (GUID) of a reusable request body component to link. Omit to keep whatever component the request body is currently linked to.
detachRequestBodyComponent	boolean	No (default false)	Set true to remove the request body component link, so the endpoint's own schemaId/schemaJson takes effect in the exported spec. Cannot be combined with requestBodyComponentId.
itemSchemaJson	string	No	OpenAPI 3.2 only: item schema of a sequential media type (jsonl, json-seq, SSE); omit to keep, empty string to clear
mediaTypeComponentId	string	No	OpenAPI 3.2 only: media type component id the content entry references ($ref); omit to keep
detachMediaTypeComponent	boolean	No (default false)	Remove the media type component link
serializedExample	string	No	3.2 only: example in wire form (serializedValue); omit keeps, empty string clears

update_endpoint

Update an existing endpoint. Requires the rowVersion from get_endpoint 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
endpointId	string	Yes	Public ID (GUID) of the endpoint to update
path	string	Yes	Endpoint path (e.g., '/users/{id}')
method	string	Yes	HTTP method: 'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'query'
rowVersion	string	Yes	Base64-encoded row version from get_endpoint (for concurrency control)
summary	string	No	Short summary of what the endpoint does
description	string	No	Detailed description of the endpoint
operationId	string	No	Unique operation ID (e.g., 'getUser', 'createOrder')
tags	string	No	Comma-separated tags (e.g., 'users,admin,public')
isDeprecated	boolean	No (default false)	Whether the endpoint is deprecated (default false)
internalNotes	string	No	Internal notes (not visible in public API docs). Omit to keep the existing notes.

update_parameter

Update an existing parameter on an endpoint (name, location, type, required, description, etc.). Use this to change an existing parameter; to add a new one use add_parameter. Requires the parameter's rowVersion for optimistic concurrency control. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
parameterId	string	Yes	Public ID (GUID) of the parameter to update
name	string	Yes	Parameter name (e.g., 'id', 'page', 'Authorization')
location	string	Yes	Parameter location: 'path', 'query', 'header', 'cookie', or 'querystring' (3.2 specs only)
schemaType	string	Yes	Schema type: 'string', 'integer', 'number', 'boolean', 'array', 'object'
rowVersion	string	Yes	Base64-encoded row version of the parameter (for concurrency control)
required	boolean	No (default false)	Whether the parameter is required (default false, path params are always required)
description	string	No	Description of the parameter
schemaFormat	string	No	Schema format (e.g., 'date-time', 'email', 'uuid', 'int32', 'int64')
example	string	No	Example value for the parameter. A bare value is fine ('us', '42'); JSON is accepted too.
defaultValue	string	No	Default value for the parameter
isDeprecated	boolean	No (default false)	Whether the parameter is deprecated (default false)
schemaId	string	No	Public ID (GUID) of a schema to link; when set, the parameter's schema is exported as a $ref to that component and schemaType is ignored on export. Omitting it preserves an existing link.
style	string	No	OpenAPI style keyword ('form', 'deepObject', 'simple', 'cookie' (3.2), …); omit for the default
explode	boolean	No	OpenAPI explode; omit for the default
contentType	string	No	Querystring media type (default form-urlencoded)
serializedExample	string	No	3.2 only: example in wire form (serializedValue)

update_response

Update an existing response on an endpoint (status code, description, content type, schema, example). Response headers and a fixture-backed example reference are always preserved as-is; the response component link is preserved unless responseComponentId names a different one or detachResponseComponent is true. Use this to change an existing response; to add a new one use add_response. Requires the response's rowVersion for optimistic concurrency control. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointId	string	Yes	Public ID (GUID) of the endpoint
responseId	string	Yes	Public ID (GUID) of the response to update
statusCode	integer	Yes	HTTP status code (e.g., 200, 201, 400, 404, 500)
rowVersion	string	Yes	Base64-encoded row version of the response (for concurrency control)
description	string	No	Description of the response
contentType	string	No (default "application/json")	Response content type (default 'application/json')
schemaJson	string	No	Inline JSON Schema definition for the response body
example	string	No	Example response body
schemaId	string	No	Public ID (GUID) of an existing schema to reference (alternative to schemaJson)
responseComponentId	string	No	Public ID (GUID) of a reusable response component to link. Omit to keep whatever component the response is currently linked to.
detachResponseComponent	boolean	No (default false)	Set true to remove the response component link, so the response's own schemaId/schemaJson takes effect in the exported spec. Cannot be combined with responseComponentId.
itemSchemaJson	string	No	OpenAPI 3.2 only: item schema of a sequential media type; omit to keep, empty string to clear
mediaTypeComponentId	string	No	OpenAPI 3.2 only: media type component id the content entry references ($ref); omit to keep
detachMediaTypeComponent	boolean	No (default false)	Remove the media type component link
serializedExample	string	No	3.2 only: example in wire form (serializedValue); omit keeps, empty string clears