mcp — Tool Reference

Connect remote MCP servers. Their tools become available through Kyew (MCP aggregation).

Actions

add

Parameters

Name	Type	Required	Description
action	string	Yes	`"add"`
server_url	string	Yes	URL of the remote MCP server (Streamable HTTP)
name	string	Yes	Display name for the server
tool_prefix	string	No	Prefix for the gateway tool name (defaults to server name)
connection_id	string	No	ID of a stored connection for auth (see `connection` tool)
headers	object	No	Raw HTTP headers to send with requests (e.g., `{"Authorization": "Bearer ..."}`)

Example request

{
  "name": "mcp",
  "arguments": {
    "action": "add",
    "server_url": "https://mcp.example.com/mcp",
    "name": "GitHub",
    "tool_prefix": "github",
    "connection_id": "conn_abc123"
  }
}

Example response

{
  "success": true,
  "server_id": "srv_k7x9m2",
  "name": "GitHub",
  "status": "active",
  "tools_discovered": 12
}

remove

Disconnect a remote MCP server and remove its gateway tool.

Parameters

Name	Type	Required	Description
action	string	Yes	`"remove"`
server_id	string	Yes	ID of the server to remove

Example request

{
  "name": "mcp",
  "arguments": {
    "action": "remove",
    "server_id": "srv_k7x9m2"
  }
}

Example response

{
  "success": true,
  "message": "Server disconnected."
}

list

List all connected remote MCP servers and their status.

Parameters

Name	Type	Required	Description
action	string	Yes	`"list"`

Example request

{
  "name": "mcp",
  "arguments": {
    "action": "list"
  }
}

Example response

{
  "servers": [
    {
      "id": "srv_k7x9m2",
      "name": "GitHub",
      "url": "https://mcp.example.com/mcp",
      "prefix": "github",
      "status": "active",
      "tools": 12,
      "connection_id": "conn_abc123",
      "last_error": null,
      "cached_at": "2026-03-14T10:30:00.000Z"
    }
  ],
  "total": 1
}

discover

List all tools available on a connected remote server.

Parameters

Name	Type	Required	Description
action	string	Yes	`"discover"`
server_id	string	Yes	ID of the server to discover tools from

Example request

{
  "name": "mcp",
  "arguments": {
    "action": "discover",
    "server_id": "srv_k7x9m2"
  }
}

Example response

{
  "server_id": "srv_k7x9m2",
  "tools": [
    { "name": "list_repos", "description": "List repositories for the authenticated user" },
    { "name": "create_issue", "description": "Create a new issue in a repository" },
    { "name": "search_code", "description": "Search for code across repositories" }
  ],
  "total": 3
}

refresh

Force-refresh the cached tool list for a connected server. Useful when the remote server has added or changed tools.

Parameters

Name	Type	Required	Description
action	string	Yes	`"refresh"`
server_id	string	Yes	ID of the server to refresh

Example request

{
  "name": "mcp",
  "arguments": {
    "action": "refresh",
    "server_id": "srv_k7x9m2"
  }
}

Example response

{
  "server_id": "srv_k7x9m2",
  "tools_refreshed": 14,
  "message": "Tool cache refreshed."
}

Gateway tools

When you add a remote MCP server, Kyew materializes a single gateway tool named after tool_prefix. This keeps your tool list compact regardless of how many tools the remote server exposes.

Use the gateway tool with three actions:

tools — List all tools available on the remote server.
search — Search tools by name or description. Returns full inputSchema for progressive discovery.
call — Execute a specific tool on the remote server.

// List available tools
{ "name": "github", "arguments": { "action": "tools" } }

// Search for a tool (returns inputSchema)
{ "name": "github", "arguments": { "action": "search", "query": "create issue" } }

// Call a tool
{
  "name": "github",
  "arguments": {
    "action": "call",
    "tool_name": "create_issue",
    "args": { "repo": "kyew/docs", "title": "Update API reference", "body": "..." }
  }
}

Tool caches refresh automatically after 24 hours. Use the refresh action to force an update.