internal/website/content/en/docs/mcp.md
Go Micro provides built-in support for the Model Context Protocol (MCP), enabling AI agents like Claude to discover and interact with your microservices as tools.
MCP gateway automatically exposes your microservices as AI-accessible tools through:
/mcp) for browser MCP clients/mcp/ws for streaming agent frameworks/mcp/tools and /mcp/call for simple tool accessSimply write Go doc comments on your handler methods:
package main
import (
"context"
"go-micro.dev/v6"
)
type GreeterService struct{}
// SayHello greets a person by name. Returns a friendly greeting message.
//
// @example {"name": "Alice"}
func (g *GreeterService) SayHello(ctx context.Context, req *HelloRequest, rsp *HelloResponse) error {
rsp.Message = "Hello " + req.Name
return nil
}
type HelloRequest struct {
Name string `json:"name" description:"Person's name to greet"`
}
type HelloResponse struct {
Message string `json:"message" description:"Greeting message"`
}
func main() {
service := micro.NewService("greeter")
service.Init()
// Register handler - docs extracted automatically from comments!
service.Handle(new(GreeterService))
service.Run()
}
That's it! Documentation is automatically extracted from your Go comments.
# Start your service
go run main.go
# In another terminal, start MCP server with stdio
micro mcp serve
Add to Claude Code config (`~/.claude/claude_desktop_config.json`):
{
"mcpServers": {
"go-micro": {
"command": "micro",
"args": ["mcp", "serve"]
}
}
}
Start MCP gateway with HTTP/SSE:
micro mcp serve --address :3000
Access tools at `http://localhost:3000/mcp/tools\`
For spec-compliant MCP clients (browser and desktop agents), use the streamable-HTTP endpoint at http://localhost:3000/mcp — see Streamable-HTTP Transport below.
Claude can now discover and call your service:
User: "Say hello to Bob using the greeter service"
Claude: [calls greeter.GreeterService.SayHello with {"name": "Bob"}]
"Hello Bob"
Go Micro automatically extracts documentation from your handler method comments at registration time. No extra code needed!
For complete documentation details, see the gateway/mcp package documentation.
MCP tool calls go through the same authentication and scope enforcement as regular API calls. This means you can control which tokens (and therefore which users, services, or AI agents) can invoke which tools.
Set endpoint scopes — Visit /auth/scopes and set required scopes on service endpoints. For example, set internal on billing.Billing.Charge to restrict it.
Create scoped tokens — Visit /auth/tokens and create tokens with specific scopes:
internal can call endpoints requiring internal* has unrestricted access (admin)403 ForbiddenUse the token — Pass it in the Authorization header for API/MCP calls:
# List available MCP tools (requires valid token)
curl http://localhost:8080/mcp/tools \
-H "Authorization: Bearer <token>"
# Call a specific tool (scope-checked)
curl -X POST http://localhost:8080/mcp/call \
-H "Authorization: Bearer <token>" \
-d '{"tool":"greeter.GreeterService.SayHello","input":{"name":"World"}}'
| Use Case | Token Scopes | What It Can Do |
|---|---|---|
| Internal tooling | internal | Call endpoints tagged with internal scope |
| Production AI agent | greeter, users | Only call greeter and user service endpoints |
| Admin / debugging | * | Full access to all tools |
| Read-only agent | readonly | Call endpoints tagged with readonly scope |
The agent playground at /agent uses the logged-in user's session token. Scope checks apply based on the scopes of the user's account. The default admin user has * scope (full access).
The `micro mcp` command provides tools for working with MCP:
# Start MCP server (stdio by default)
micro mcp serve
# Start with HTTP transport
micro mcp serve --address :3000
# List available tools
micro mcp list
# Test a specific tool
micro mcp test greeter.GreeterService.SayHello
The MCP gateway serves four transports from one HTTP server (or stdio when no address is set):
micro mcp serve./mcp. The endpoint for browser MCP clients; CORS is enabled so it works without a proxy./mcp/ws for streaming agent frameworks./mcp/tools and /mcp/call.See examples for complete usage.
Point any spec-compliant MCP client (Claude desktop, browser agents) at http://localhost:3000/mcp. The client SDK handles the handshake; the endpoint behaves like this:
POST /mcp with initialize mints a session, returned in the Mcp-Session-Id response header:curl -i -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'
# Mcp-Session-Id: <session-id> <- echo this header on later requests
POST /mcp with tools/list and tools/call, echoing the session id:curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id>" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id>" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"greeter.GreeterService.SayHello","arguments":{"name":"World"}}}'
GET /mcp opens a text/event-stream for server→client messages; DELETE /mcp terminates the session. JSON-RPC notifications (no id) return 202 Accepted with no body.Supported methods: initialize, ping, tools/list, tools/call. Tool calls share the same auth, scope, rate-limit, circuit-breaker, and x402 payment pipeline as the REST endpoints, so scopes set in /auth/scopes are enforced identically.
The MCP gateway is its own server, independent of the HTTP API gateway. The CLI (micro gateway --mcp-address :3000, or micro run --mcp-address :3000) starts both servers and shuts them down together; library users start each explicitly with mcp.NewServer.
See `examples/mcp/documented` for a complete working example.