Documentation

MCP (Model Context Protocol)

Shirube speaks MCP both ways: consume GitHub/Linear as tools, and serve your internal tools to Cursor or Claude Desktop.

What it is

MCP is a standard for exposing tools to models. Shirube speaks it both ways:

Direction	Meaning	Use
Consume (external)	Shirube is the client. GitHub, Linear, browser servers become agent tools	“Create a GitHub issue from this ticket”
Serve (internal)	Shirube is the server. Your `tool()` functions appear in Cursor, Claude Desktop, or another agent	One catalog of `refund` / `search_docs` for humans and agents

Configure once at process start. Every Agent inherits the catalogs unless you .mcp(false).

Consume external servers

Stdio (local process) or HTTP/SSE (hosted):

mcp-consume.ts

import { mcp } from "shirube-ai";

mcp.configure({
  external: [
    {
      name: "github",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
    },
    {
      name: "linear",
      url: "https://mcp.linear.app/mcp",
      headers: { Authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
    },
  ],
});

const agent = Agent.builder()
  .name("ops")
  .instructions("You may use GitHub and Linear tools when the user asks.")
  .apiKey(key)
  .mcp()
  .build();

Tool names are namespaced: github__create_issue, not create_issue, so two servers cannot collide. agent.run() connects lazily. await agent.connect() if you want to fail at boot. await agent.close() to stop stdio children.

Per-agent filters:

mcp-filters.ts

.mcp({
  internal: true,
  external: ["github"],
  include: ["github__*"],
  exclude: ["github__delete_*"],
  servers: [{ name: "slack", url: "https://mcp.slack.com/mcp" }],
})

.mcp(false)

Local .tools([...]) always win if a name clashes with MCP.

Serve internal tools

mcp-serve.ts

mcp.configure({
  internal: [refund, searchDocs],
});

await mcp.serve({ transport: "stdio" });
await mcp.serve({ transport: "http", port: 3333, path: "/mcp" });

await agent.serveMcp({ transport: "stdio" });

Point Cursor / Claude Desktop at the stdio command or the HTTP URL. The same execute functions run.

mcp.internal.register(tool) adds to the catalog after configure.

Model providers and routing

Tracing, reliability, and errors