MCP Server Spec

This page defines the requirements and conventions for MCP servers that integrate with Cosmo. Cosmo implements the Model Context Protocol spec — any compliant MCP server works without modification.

Transport requirements

Cosmo supports three transports:

Transport	When to use
`stdio`	Local servers — run as a child process on the user's machine
`streamable-http`	Remote servers — HTTP streaming with optional OAuth 2.1
`sse`	Remote servers using the legacy SSE transport

For new integrations, prefer streamable-http. It supports OAuth 2.1 natively (the REMOTE_OAUTH auth mode) and is the direction the MCP spec is moving.

Tool naming conventions

Tool names must be lowercase with underscores. Cosmo namespaces them with the server ID when presenting them to the AI:

mcp__<server_id>__<tool_name>

For example, a tool named search on a server with ID notion becomes mcp__notion__search in the AI's tool list.

Keep tool names short and verb-first: search, create_page, list_databases.

Tool schema

Each tool must include a JSON Schema for its inputSchema. Cosmo passes this schema directly to the LLM — well-described schemas produce better AI behavior.

{
  "name": "search",
  "description": "Search Notion pages by keyword. Returns page titles, IDs, and snippets.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "limit": {
        "type": "number",
        "description": "Max results to return (default: 10)"
      }
    },
    "required": ["query"]
  }
}

Guidelines:

Tool descriptions should explain what the tool does AND when the AI should use it
Property descriptions should describe the expected format, not just the name
Mark only truly required fields as required
Use enum for fields with fixed value sets

Auth modes

Cosmo supports four auth modes for connectors. Your server's auth requirements determine which mode to use:

Mode	Description
`NONE`	No auth needed (local tools, public APIs)
`API_KEY`	User provides a token; stored encrypted in Cosmo's DB
`SERVER_MEDIATED`	Cosmo proxies an OAuth flow (Notion, Google, ClickUp)
`REMOTE_OAUTH`	The MCP server handles OAuth 2.1 directly (Atlassian)

For REMOTE_OAUTH, your server must implement the OAuth 2.1 authorization server metadata endpoint:

GET /.well-known/oauth-authorization-server

Cosmo's RemoteOAuthProvider handles the client side automatically.

Resource and prompt support

Resources and prompts are optional but recommended:

Resources — expose structured data (e.g., a list of databases, a file tree) that the AI can read without making a tool call
Prompts — pre-built prompt templates users can invoke from the UI

Resources and prompts follow the standard MCP spec. Cosmo surfaces them in the connector UI when present.

Error handling

Return MCP-standard error responses for tool failures. Do not throw unhandled exceptions — they surface as opaque errors to the user.

// Return a structured error
return {
  content: [{ type: 'text', text: 'Error: page not found' }],
  isError: true,
}

Testing your server locally

Build your server and ensure it can be started with a single command (e.g., node dist/index.js)
Add it to Cosmo as a custom connector with the stdio transport
Open a chat session and verify the tools appear in the AI's context
Test each tool by asking the AI to use it

See Building Integrations for a step-by-step walkthrough.