Peekaboo/docs/MCP.md

Model Context Protocol (MCP) in Peekaboo

This document explains how Peekaboo integrates external MCP servers through TachikomaMCP, and how to configure and test transports (stdio, HTTP, SSE) from the CLI.

Overview

Peekaboo can consume tools exposed by any MCP-compatible server. We currently support three transport modes via TachikomaMCP:

• stdio: spawn a local process and talk over stdio using MCP framing
• http (streamable HTTP): single HTTP endpoint for request/response streaming
• sse (Server-Sent Events): single URL; GET establishes a read stream and the same URL accepts POST JSON-RPC writes

All transports converge to a single client that performs:

• initialize → notifications/initialized → tools/list → tools/call
• Strict per-request timeout (defaults 10s from the CLI; probe honors it)

CLI usage

List high-level help:

peekaboo mcp --help

Add an MCP server (stdio example):

peekaboo mcp add files -- npx -y @modelcontextprotocol/server-filesystem /Users/me/docs

Add an MCP server (SSE example) with headers:

peekaboo mcp add my-sse --transport sse \
  --header "Authorization=Bearer $TOKEN" \
  --timeout 10 -- https://example.com/mcp/sse

Arguments after -- fill command and optional args. For SSE, command is the URL.

Test the connection (respects --timeout):

peekaboo mcp test my-sse

List configured servers and health:

peekaboo mcp list

Configuration model

Entries are persisted to the user profile config (JSON) under mcpClients. Effective config keys are:

• transport: "stdio" | "http" | "sse"
• command: for stdio: executable; for http/sse: URL
• args: array (stdio only)
• env: map of environment variables (stdio)
• headers: map of HTTP headers (http/sse)
• enabled: boolean
• timeout: seconds for request timeouts and connection probing
• autoReconnect: boolean
• description: optional string

Example (SSE):

{
  "mcpClients": {
    "context7-url": {
      "transport": "sse",
      "command": "https://api.context7.com/mcp/sse",
      "headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" },
      "enabled": true,
      "timeout": 10
    }
  }
}

Environment variables in the JSON are expanded at load time (e.g. ${CONTEXT7_API_KEY}).

SSE transport specifics

• Single URL model: the same URL is used for both the read stream (GET with Accept: text/event-stream) and the write channel (POST JSON-RPC with Content-Type: application/json).
• Headers: any --header Key=Value pairs you pass at mcp add are applied to both the GET (read) and POST (write) requests.
• Endpoint event: servers may optionally emit an endpoint SSE event containing a string URL or a JSON object like { "url": "/rpc" }. We accept either form, resolved relative to the base URL. If not emitted, we continue using the same URL.
• Timeouts: per-request timeout is enforced by the client; CLI defaults to 10 seconds.

Troubleshooting

• initialize times out after ~10s:
  • Check that Authorization or other required headers are provided (--header).
  • Confirm the server supports POST on the SSE URL and speaks MCP initialize.

Notes

• Peekaboo’s SSE client now forwards custom headers on the GET request in addition to POST.
• The endpoint event is accepted as either a string or a JSON object with url/endpoint.