MCP skills API

Manage skill-embedded MCP servers that provide additional tools to agents. Each skill can bundle its own MCP server with a set of tools. Activate a skill’s MCP server on demand and deactivate it when no longer needed.

All MCP skill endpoints require session-based authentication through NextAuth. Idle MCP servers are automatically cleaned up.

Activate a skill MCP

POST /api/mcp/:skillId

Starts the MCP server bundled with the specified skill. Returns the server metadata including its name, version, available tools, and activation timestamp.

Path parameters

Parameter	Type	Required	Description
`skillId`	string	Yes	Identifier of the skill whose MCP server to activate

Built-in skills

The following skills ship with built-in MCP servers:

Skill ID	Description
`websearch`	Web search tool server
`context7`	Context retrieval and semantic search
`grep_app`	Code search using grep patterns

Response

{
  "success": true,
  "skillId": "websearch",
  "mcp": {
    "name": "websearch-mcp",
    "version": "1.0.0",
    "tools": ["web_search", "web_fetch"],
    "startedAt": "2026-04-04T12:00:00.000Z"
  }
}

Field	Type	Description
`success`	boolean	Whether activation succeeded
`skillId`	string	The skill that was activated
`mcp.name`	string	MCP server name from the skill configuration
`mcp.version`	string	MCP server version
`mcp.tools`	string[]	List of tool names provided by this MCP server
`mcp.startedAt`	string	ISO 8601 timestamp of when the server was started

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to activate MCP. The error message describes the failure (for example, skill not found or server failed to start).

Deactivate a skill MCP

DELETE /api/mcp/:skillId

Stops the MCP server for the specified skill and frees its resources.

Path parameters

Parameter	Type	Required	Description
`skillId`	string	Yes	Identifier of the skill whose MCP server to deactivate

Response

{
  "success": true,
  "skillId": "websearch",
  "message": "MCP deactivated"
}

Field	Type	Description
`success`	boolean	Whether deactivation succeeded
`skillId`	string	The skill that was deactivated
`message`	string	Confirmation message

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to deactivate MCP. The error message describes the failure.

Call an MCP tool

POST /api/mcp/:skillId/call/:toolName

Invokes a specific tool on an active MCP server. The skill’s MCP server must be activated before calling its tools. Requires session authentication.

Path parameters

Parameter	Type	Required	Description
`skillId`	string	Yes	Identifier of the skill whose MCP server to call
`toolName`	string	Yes	Name of the tool to invoke

Request body

The request body should be a JSON object containing the tool parameters. You can either pass parameters directly as the body or wrap them in a parameters key:

{
  "parameters": {
    "query": "search term"
  }
}

Or directly:

{
  "query": "search term"
}

An empty body or no body is allowed for tools that take no parameters.

Response (200)

{
  "skillId": "websearch",
  "toolName": "web_search",
  "success": true,
  "result": {}
}

Field	Type	Description
`skillId`	string	The skill that was called
`toolName`	string	The tool that was invoked
`success`	boolean	Whether the tool call succeeded
`result`	any	Tool-specific result data

Response (400)

When the tool call fails (for example, invalid parameters):

{
  "skillId": "websearch",
  "toolName": "web_search",
  "success": false,
  "error": "Invalid parameters"
}

Errors

Code	Description
401	Unauthorized — no valid session
400	Tool call failed. The response includes `success: false` and an error message.
500	Failed to call MCP tool. The error message describes the failure.

Automatic idle cleanup

MCP servers that remain idle are automatically deactivated to free resources. You do not need to manually deactivate servers that are no longer in use, though explicit deactivation is recommended when you know a skill’s tools are no longer needed.

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

MCP skills API

MCP skills API

Activate a skill MCP

Path parameters

Built-in skills

Response

Errors

Deactivate a skill MCP

Path parameters

Response

Errors

Call an MCP tool

Path parameters

Request body

Response (200)

Response (400)

Errors

Automatic idle cleanup

​MCP skills API

​Activate a skill MCP

​Path parameters

​Built-in skills

​Response

​Errors

​Deactivate a skill MCP

​Path parameters

​Response

​Errors

​Call an MCP tool

​Path parameters

​Request body

​Response (200)

​Response (400)

​Errors

​Automatic idle cleanup

MCP skills API

Activate a skill MCP

Path parameters

Built-in skills

Response

Errors

Deactivate a skill MCP

Path parameters

Response

Errors

Call an MCP tool

Path parameters

Request body

Response (200)

Response (400)

Errors

Automatic idle cleanup