Authoring MCP servers

Build once, use it from many clientsCopy Anchor Link

An MCP server turns an API, local service, or workflow into tools that omp can discover and use. Choose MCP when the integration should also work with other MCP clients. For an omp-only integration, a custom tool is usually smaller.

The quickest path is a local stdio server. The official SDK handles JSON-RPC framing, version negotiation, and the initialization sequence, so your code can focus on tool schemas and behavior.

Build a minimal stdio serverCopy Anchor Link

npm install @modelcontextprotocol/server zod

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({
  name: "hello",
  version: "1.0.0",
});

server.registerTool(
  "greet",
  {
    description: "Greet one person by name.",
    inputSchema: z.object({
      name: z.string().min(1).describe("The person's name"),
    }),
  },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  }),
);

await server.connect(new StdioServerTransport());

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "hello": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp/hello-server.mjs"]
    }
  }
}

/mcp reload
/mcp test hello

Choose a transportCopy Anchor Link

stdio is the default when type is absent. A remote entry without "type": "http" is therefore treated as stdio and fails because it has no command.

Publish the same tool over Streamable HTTPCopy Anchor Link

The current SDK can serve both current and 2025-era clients. For a small Node-hosted endpoint, install its Node adapter:

npm install @modelcontextprotocol/node

A minimal loopback server looks like this:

import { createServer } from "node:http";
import {
  localhostHostValidation,
  localhostOriginValidation,
  toNodeHandler,
} from "@modelcontextprotocol/node";
import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";
import * as z from "zod/v4";

const handler = createMcpHandler(() => {
  const server = new McpServer({ name: "hello-http", version: "1.0.0" });
  server.registerTool(
    "greet",
    {
      description: "Greet one person by name.",
      inputSchema: z.object({ name: z.string().min(1) }),
    },
    async ({ name }) => ({
      content: [{ type: "text", text: `Hello, ${name}!` }],
    }),
  );
  return server;
});

const nodeHandler = toNodeHandler(handler);
const validateHost = localhostHostValidation();
const validateOrigin = localhostOriginValidation();

createServer((request, response) => {
  if (!validateHost(request, response) || !validateOrigin(request, response)) return;
  void nodeHandler(request, response);
}).listen(3000, "127.0.0.1");

Configure the running endpoint:

{
  "mcpServers": {
    "hello-http": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Public protocol contractCopy Anchor Link

Using an MCP SDK is strongly recommended. If you implement the wire protocol yourself, these are the interoperability points omp relies on:

For Streamable HTTP, preserve Mcp-Session-Id when you issue one and accept MCP-Protocol-Version: 2025-11-25 on requests after initialization. Support the HTTP methods, status codes, media types, and optional SSE channel defined by the public MCP transport specification. The official SDK handles these details.

omp sends numeric JSON-RPC request IDs by default. A server should accept both JSON-RPC-permitted forms; requiring one representation reduces compatibility with other clients.

Define tools that travel wellCopy Anchor Link

A listed tool needs a stable name, a concrete description, and an inputSchema whose top level is a JSON Schema object. With the SDK above, a Standard Schema library such as Zod produces that schema for you.

Good schemas help the client select the tool and construct valid arguments:

• Describe the user-visible action and when it is appropriate.
• Use explicit property descriptions, bounds, enums, and required fields.
• Keep optional fields genuinely optional; do not require clients to send empty placeholders.
• Validate permissions and inputs again in the handler. A schema is guidance and validation, not authorization.
• Keep names stable once users depend on them.

omp namespaces discovered tools by server, lowercases their names, replaces characters outside [a-z_] with underscores, and caps the mounted name at 64 characters with a stable hash suffix when needed. Distinct raw names that normalize identically collide; omp keeps one deterministic winner. Prefer short, distinct lowercase names such as search_issues or create_invoice. Users ask for the capability in natural language rather than typing the mounted name.

Return results and errorsCopy Anchor Link

Every successful call should return content. Text is the most portable content type:

return {
  content: [{ type: "text", text: "Created invoice INV-1042." }],
};

omp also accepts MCP image content (data as base64 plus mimeType) and embedded resource content. If you also return structuredContent, include a useful text representation in content; do not make the human-readable result depend on structured output support.

Use isError: true for an expected, user-correctable failure. This keeps the failure attached to the tool call and gives the model information it can act on:

return {
  content: [{ type: "text", text: "Customer C-17 does not exist." }],
  isError: true,
};

For protected HTTP tools, a standards-based authorization challenge may be returned with an error in _meta["mcp/www_authenticate"]. omp recognizes that public MCP challenge and can reauthorize before retrying when the server is configured for OAuth.

Debugging loopCopy Anchor Link

npx @modelcontextprotocol/inspector node ./mcp/hello-server.mjs

Troubleshooting symptomsCopy Anchor Link

Ship checklistCopy Anchor Link

• The server negotiates 2025-11-25 with omp and does not send session traffic before initialization completes.
• stdio stdout contains protocol frames only; hosted HTTP has TLS, authentication, and Host/Origin validation.
• tools/list returns stable names, descriptions, object input schemas, and every pagination cursor correctly.
• Every tools/call path returns useful content; expected failures return isError: true.
• The Inspector can list and call each tool, and /mcp test <name> reports the same inventory.
• A natural-language request in omp exercises the real handler successfully.

RelatedCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.