MCP servers

Attach managed HTTPS MCP servers with useMcpServer

MCP (Model Context Protocol) connects an agent to tools hosted by an external service. Declare the server once with defineMcpServer(), then attach it to an agent render with useMcpServer().

Connect a server

import {
  defineMcpServer,
  useMcpServer,
  useModel,
} from "@opencomputer/agent";

const docs = defineMcpServer({
  id: "company-docs",
  url: "https://mcp.example.com/server",
});

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  useMcpServer(docs);
  return "Answer questions using the company documentation when relevant.";
}

Managed MCP URLs must use HTTPS. OpenComputer connects to the server and makes its tools available to the managed agent loop; agent code does not open or close the connection itself.

Definition fields

Field	Required	Purpose
id	yes	Stable ID for the server in the deployment
url	yes	HTTPS MCP endpoint
connection	no	Secret-backed HTTP connection used to authorize the server

useMcpServer() accepts either a definition or an existing server ID.

Attach authorization

Reference a secret-backed HTTP connection when the server requires authorization:

import {
  bearer,
  defineConnection,
  defineMcpServer,
  useSecret,
  useMcpServer,
} from "@opencomputer/agent";

const github = defineConnection({
  id: "github-mcp-auth",
  origin: "https://api.githubcopilot.com",
  headers: {
    Authorization: bearer(useSecret("GITHUB_PAT")),
  },
});
const githubMcp = defineMcpServer({
  id: "github",
  url: "https://api.githubcopilot.com/mcp/",
  connection: github,
});

export default function Agent() {
  useMcpServer(githubMcp);
  return "Use GitHub tools to investigate repository questions.";
}

The declaration contains only a secret reference. Set the secret with opencomputer secrets set GITHUB_PAT; its value is injected only into requests to the declared origin. See Secrets and outbound requests.

Managed catalogs

Some catalogs are built into the platform: attach them by name and the credential is supplied by OpenComputer — no secret to set, no connection to declare. The Monid catalog is the first:

import { monid, useMcpServer } from "@opencomputer/agent";

const tools = monid();

export default function Agent() {
  useMcpServer(tools);
  return "Discover tools in the catalog when a request needs them.";
}

monid() selects the managed monid MCP server (https://mcp.monid.ai/v1), which exposes catalog meta-tools — discover, inspect, and run — covering hundreds of providers. useMcpServer("monid") selects it the same way. When you define a monid connection or MCP server yourself, yours wins and monid() is a compile error.

The catalog key is a platform credential resolved at the platform’s egress edge. It only ever reaches mcp.monid.ai and api.monid.ai; agent code and your project’s own secrets never see it. The same platform scope is available on useSecret() for connection headers when a deployment declares a platform-managed credential by name.

Attach MCP conditionally

An agent can expose a server only when the current request needs it:

import { useInput, useMcpServer } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  if (input.text?.toLowerCase().includes("documentation")) {
    useMcpServer(docs);
  }
  return "Use company docs when that capability is available.";
}

Conditional attachment reduces the number of tools the model must choose from on unrelated requests.

MCP versus code-defined tools

Use code-defined tools when you own the operation or need custom validation and control. Use MCP when a service already publishes the tools you need or when several agents should consume the same remote tool set.