mcp-server

MCP Server

Author a Model Context Protocol server that exposes typed tools, resources, and prompts to agents. Go with the official github.com/modelcontextprotocol/go-sdk is the default; Python and TypeScript use their official SDKs. Registering a finished server in a host belongs to agent-mcp.

Workflow

1. Pick the stack: Go for a binary that ships by go install or ko; Python or TypeScript when the project already lives there.

   go get github.com/modelcontextprotocol/go-sdk@latest                      # package mcp; skip -pre tags
   uv add "mcp[cli]"                                                        # from mcp.server import MCPServer (formerly FastMCP)
   pnpm add @modelcontextprotocol/server @modelcontextprotocol/node         # McpServer + stdio; node adds Streamable HTTP
   

2. Define typed tools: one struct (or type-hinted function) per tool; the SDK derives the JSON Schema from struct tags or type hints, so the schema never drifts from the code. Go: mcp.NewServer(&mcp.Implementation{Name: "<slug>", Version: "v0.1.0"}, nil) then mcp.AddTool(server, &mcp.Tool{Name: "...", Description: "..."}, handler).
3. Choose the transport: stdio for a local tool, Streamable HTTP for a hosted one, mounted as a plain http.Handler.

   err := server.Run(ctx, &mcp.StdioTransport{}) // local
   handler := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return server }, &mcp.StreamableHTTPOptions{Stateless: true})
   err = http.ListenAndServe(":"+os.Getenv("PORT"), handler) // Cloud Run injects PORT
   

   Python: uv run mcp run server.py --transport streamable-http; TypeScript: StdioServerTransport from @modelcontextprotocol/server/stdio or the HTTP transport from @modelcontextprotocol/node.
4. Test locally with the Inspector before wiring any host; unit-test through the in-memory transport (mcp.NewInMemoryTransports() in Go, Client(mcp) in Python) so the suite needs no subprocess.

   npx @modelcontextprotocol/inspector ./bin/<slug>                            # stdio, web UI (Python: uv run mcp dev server.py)
   npx @modelcontextprotocol/inspector --cli ./bin/<slug> --method tools/list  # scripted
   npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:8080/mcp
   

5. Ship: local servers install as a binary (go install, uv tool install); hosted servers containerize per containerize and deploy per cloud-run, private by default with an identity token or OAuth in front.
6. Register the server in each host with agent-mcp and verify one real tool call end to end.