MCP gateway: add per-tool scopes, tracing, rate limiting, and audit logging

[Copilot]

Adds fine-grained auth scopes, request tracing, rate limiting, and audit logging to the MCP gateway — motivated by user feedback on least-privilege authz and traceability for agent-initiated tool calls.

Server-side: scope declaration at handler registration

New server.WithEndpointScopes() helper, consistent with existing WithEndpointDescription() / WithEndpointExample():

handler := service.Server().NewHandler(
    new(BlogService),
    server.WithEndpointScopes("Blog.Create", "blog:write"),
    server.WithEndpointScopes("Blog.Delete", "blog:write", "blog:admin"),
)

Gateway-side: auth, scopes, rate limiting, tracing, audit

• Options.Auth — auth.Auth provider for token inspection; enforces per-tool scopes from endpoint metadata
• Options.Scopes — gateway-level scope overrides per tool name, without changing services
• Options.RateLimit — per-tool token-bucket rate limiting
• Options.AuditFunc — callback with immutable AuditRecord for every tool call (allowed or denied)
• Trace IDs — UUID generated per call, propagated via Mcp-Trace-Id / Mcp-Tool-Name / Mcp-Account-Id metadata to downstream RPCs

mcp.Serve(mcp.Options{
    Registry: reg,
    Auth:     jwtAuth,
    Scopes: map[string][]string{
        "blog.Blog.Delete": {"blog:admin"},
    },
    RateLimit: &mcp.RateLimitConfig{RequestsPerSecond: 10, Burst: 20},
    AuditFunc: func(r mcp.AuditRecord) {
        log.Printf("trace=%s tool=%s account=%s allowed=%v", r.TraceID, r.Tool, r.AccountID, r.Allowed)
    },
})

Scope resolution order

1. Service declares scopes via server.WithEndpointScopes() → stored as "scopes" in endpoint metadata
2. Gateway Options.Scopes overrides if present for that tool name
3. Account scopes checked against tool scopes (any-of match)

Changes

• server/doc.go — WithEndpointScopes() helper
• gateway/mcp/mcp.go — Auth, Scopes, RateLimit, AuditFunc on Options; scope/auth/rate-limit/trace enforcement in handleCallTool and discoverServices; AuditRecord type
• gateway/mcp/ratelimit.go — token-bucket rate limiter
• gateway/mcp/stdio.go — same auth/scope/rate/trace/audit flow for stdio transport
• gateway/mcp/mcp_test.go — tests for scopes, auth, rate limiting, audit, trace IDs, gateway-level scope overrides
• server/comments_test.go — test for WithEndpointScopes
• Docs/examples — DOCUMENTATION.md, examples/mcp/README.md, examples/mcp/documented/main.go updated

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 224.0.0.251
  • Triggering command: REDACTED, pid is -1 (packet block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>MCP scope's and tracing</issue_title>
<issue_description>Based on user feedback:

--
Curious how you’re thinking about boundaries here.

If an agent can call internal microservice APIs via MCP, what’s the “least privilege” story (authz, rate limits), and how do you audit/trace tool calls back to user intent?

And the follow on

---

I’m leaning toward per-tool scopes plus short‑lived tokens tied to the user’s intent. Each tool call should carry a request/trace id that maps back to the original user message, with rate limits at both the gateway and service layers. For audit, keep an immutable log of tool calls + policy decisions. A real end‑to‑end example with traces would make the model concrete.

It's clear we can introduce this sort of fine grained scoping into our tools and a way to manage it through the UI in the server.

We can use the blog app as a test case</issue_description>

<agent_instructions>Based on our new MCP integration map out what this functionality would look like based on the user request. Looking at a real world example like our blog app in github.com/micro/blog which consists of three services. If these were registered as services and tools and a user requested to post something through the agent connecting via MCP tools then we'd want Auth, tracing and rate limiting with fine grained scopes. So we need a plan of how to do that with go-micro and any additional features needed in the server and UX to manage it e.g do we have to tie micro Auth accounts to this in some way.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes MCP scope's and tracing #2849

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.