Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The mcp() tool is a unified gateway that provides access to all MCP servers and their tools through a single interface. Instead of registering hundreds of individual tools (which would consume 10,000+ tokens), the adapter exposes one proxy tool (~200 tokens) that routes requests to the appropriate MCP server.

​
Function Signature

mcp(params: {
  tool?: string;
  args?: string;
  connect?: string;
  describe?: string;
  search?: string;
  regex?: boolean;
  includeSchemas?: boolean;
  server?: string;
})

​
Parameters

​
tool
string
Tool name to call (e.g., 'chrome_devtools_take_screenshot'). Triggers call mode.
​
args
string
Arguments as a JSON string (e.g., '{"key": "value"}'). Must be a valid JSON object, not an array or primitive.Important: This is a JSON string, not an object. The string will be parsed and validated.
​
connect
string
Server name to connect to. Triggers connect mode. Forces a connection and refreshes metadata for the specified server.
​
describe
string
Tool name to describe. Triggers describe mode. Shows tool details including parameters and their schemas.
​
search
string
Search query for finding tools. Triggers search mode. Space-separated words are OR’d together (like most search engines).Searches both MCP tools and Pi tools from installed extensions.
​
regex
boolean
default:"false"
Treat the search query as a regular expression instead of space-separated terms.
​
includeSchemas
boolean
default:"true"
Include parameter schemas in search results. Set to false for compact output.
​
server
string
Filter results to a specific server. Works with search mode and list mode. Also disambiguates tool calls when multiple servers have the same tool name.

​
Operation Modes

The tool’s behavior is determined by which parameters you provide. Mode resolution follows this priority: tool > connect > describe > search > server > status See Operation Modes for detailed documentation of each mode.

​
Return Values

​
Success Response

{
  content: Array<{ type: "text" | "image"; text?: string; data?: string; mimeType?: string }>,
  details: {
    mode: "status" | "list" | "search" | "describe" | "call" | "connect",
    // ... mode-specific fields
  }
}

​
Error Response

{
  content: [{ type: "text", text: string }],
  isError: true,
  details: {
    error: string,
    // ... additional error context
  }
}
​
content
array
Array of content blocks. Text content includes tool output, status information, or error messages. May include images or other media types from MCP tools.
​
details
object
Structured metadata about the operation. Always includes a mode field. Error responses include an error field.
​
isError
boolean
Only present on error responses. Indicates that the operation failed.

​
Examples

​
Status Check

mcp({})

MCP: 2/3 servers, 47 tools

✓ chrome-devtools (26 tools)
✓ github (21 tools)
○ postgres (not connected)

mcp({ server: "name" }) to list tools, mcp({ search: "..." }) to search

​
Search Tools

mcp({ search: "screenshot navigate" })

Found 2 tools matching "screenshot navigate":

chrome_devtools_take_screenshot
  Take a screenshot of the page or element.

  Parameters:
    format (enum: "png", "jpeg", "webp") [default: "png"]
    fullPage (boolean) - Full page instead of viewport

chrome_devtools_navigate
  Navigate to a URL.

  Parameters:
    url (string) *required* - The URL to navigate to

​
Describe Tool

mcp({ describe: "chrome_devtools_take_screenshot" })

​
Call Tool

mcp({
  tool: "chrome_devtools_take_screenshot",
  args: '{"format": "png", "fullPage": true}'
})
The args parameter must be a JSON string, not an object:
// ✅ Correct
args: '{"key": "value"}'

// ❌ Wrong
args: { key: "value" }

​
Connect to Server

mcp({ connect: "chrome-devtools" })
Forces a connection and metadata refresh, then returns the tool list for that server.

​
Filter by Server

mcp({ search: "file", server: "github" })
Searches only tools from the github server.

​
Error Handling

​
Common Errors

​
init_failed
error
MCP initialization failed. Check server logs and configuration.
​
not_initialized
error
MCP not initialized. Wait for initialization to complete.
​
invalid_args
error
The args parameter contains invalid JSON.
​
invalid_args_type
error
The args parameter parsed successfully but is not a JSON object (it’s an array, null, or primitive).
​
tool_not_found
error
The requested tool was not found in any connected server. The error message includes available tools if a server was identified.
​
server_not_found
error
The specified server does not exist in the configuration.
​
server_unavailable
error
The server failed to connect. May include backoff information.
​
connect_failed
error
Failed to establish connection to the server. Check server command, args, and environment.
​
tool_error
error
The tool executed but returned an error. The error message includes the expected parameter schema to help with self-correction.
​
call_failed
error
Failed to call the tool (network error, crash, etc.). Includes expected parameter schema.

​
Tool Name Resolution

Tools are found using the following logic:
  1. Exact match - If a tool with the exact name exists, use it
  2. Normalized match - Hyphens and underscores are treated as equivalent (resolve-library-id matches resolve_library_id)
  3. Prefix match - If no match found and toolPrefix is not "none", extract the server prefix and try connecting to that server
  4. Server parameter - If server parameter is provided, only search that specific server

Build docs developers (and LLMs) love

Get started for freeTalk to us