Tools API and MCP

Introduction

The two connection tools are available to anything that can make an HTTP request: a script, a workflow engine, or an MCP client such as Claude or Cursor. Turn it on with publicApi; callers are identified by your host’s identity guard, and every call runs as that caller and is audited under them.

Turning it on

connectionProviders({ providers: [githubProvider()], publicApi: true }, ports);
// or, in an agent server
PilotooModule.forRoot({ connections: { providers: [githubProvider()], publicApi: true } });

Without publicApi the routes answer 404. With it, they need storage and CONNECTIONS_ENCRYPTION_KEYS; without them the routes also answer 404. An unidentified caller gets 401.

The HTTP API

Route	Body
POST /api/tools/search	{ query, provider?, limit? }
POST /api/tools/list	{ provider? }
POST /api/tools/execute	{ name, arguments, account? }

curl -X POST https://connect.example.com/api/tools/search \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "query": "list issues" }'

list answers every tool the caller may use, sorted by qualified name, each entry shaped as a search result; it is what the workflow editor builds its connection nodes from. All three answer HTTP 200 with exactly the JSON the tools return: { "ok": true, ... } or { "ok": false, "error": { "code", "message" } }. See Agent tools for the fields and codes. A malformed body is 400 with the validation message.

The MCP endpoint

POST /mcp is a Streamable HTTP MCP endpoint. It is stateless: each request is served on its own, GET and DELETE answer 405. It lists the same two tools with the same descriptions and input schemas. A refusal comes back as a tool result with isError: true, carrying the same JSON text.

Authenticate as for any other route, with whatever your identity guard reads. Examples for a bearer token:

.cursor/mcp.json

{ "mcpServers": { "connections": { "url": "https://connect.example.com/mcp", "headers": { "Authorization": "Bearer <token>" } } } }

Claude Code

claude mcp add --transport http connections https://connect.example.com/mcp --header "Authorization: Bearer <token>"

Next steps

• Pilotoo Connect: a ready service with sign-in and personal access tokens.
• Remote sources: the agent server side of the same API.