Files
coder/coderd/mcp/mcp.go
T
Hugo Dutka 150c680a4b fix: return MCP server tool execution errors as tool results (#29051)
Coder's MCP server currently sends most tool execution failures as
top-level JSON-RPC errors. The underlying error text is transmitted like
this:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "workspace name cannot be empty"
  }
}
```


Not all clients handle it well, and some may return a generic "MCP tool
request failed." to the model instead of passing the details as tool
output.

This PR starts returning execution failures as tool results with
`isError: true` and descriptive content like this:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "workspace name cannot be empty"
      }
    ]
  }
}
```

This should make the MCP server work better across a broader range of
MCP clients.
2026-09-08 17:28:46 +00:00

264 lines
8.2 KiB
Go

package mcp
import (
"context"
"encoding/json"
"errors"
stdslog "log/slog"
"net/http"
"github.com/modelcontextprotocol/go-sdk/mcp"
"golang.org/x/xerrors"
"cdr.dev/slog/v3"
"github.com/coder/coder/v2/buildinfo"
"github.com/coder/coder/v2/codersdk"
"github.com/coder/coder/v2/codersdk/toolsdk"
)
const (
// MCPServerName is the name used for the MCP server.
MCPServerName = "Coder"
// MCPServerInstructions is the instructions text for the MCP server.
MCPServerInstructions = "Coder MCP Server providing workspace and template management tools"
// Used in tests and aibridge.
MCPEndpoint = "/api/experimental/mcp/http"
)
// Server represents an MCP HTTP server instance
type Server struct {
Logger slog.Logger
// mcpServer is the underlying MCP server
mcpServer *mcp.Server
handler http.Handler
}
// NewServer creates a new MCP HTTP server
func NewServer(logger slog.Logger) (*Server, error) {
mcpSrv := mcp.NewServer(&mcp.Implementation{
Name: MCPServerName,
Version: buildinfo.Version(),
}, &mcp.ServerOptions{
Instructions: MCPServerInstructions,
Logger: stdslog.New(&slogHandler{logger: logger}),
})
// Stateless mode runs each request as its own short-lived session,
// omits Mcp-Session-Id, and answers GET and DELETE with 405, all
// permitted by the Streamable HTTP transport spec.
handler := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server {
return mcpSrv
}, &mcp.StreamableHTTPOptions{
Stateless: true,
// Use application/json instead of SSE framing because Coder
// tools emit no notifications and do not need a stream.
JSONResponse: true,
// coderd often listens on loopback behind a reverse proxy,
// which trips the SDK's localhost DNS-rebinding check (loopback
// local address with a public Host header). The endpoint's
// bearer authentication is the relevant access control.
DisableLocalhostProtection: true,
})
return &Server{
Logger: logger,
mcpServer: mcpSrv,
handler: handler,
}, nil
}
// ServeHTTP implements http.Handler interface
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
s.handler.ServeHTTP(w, r)
}
// Register all available MCP tools with the server excluding:
// - ReportTask - which requires dependencies not available in the remote MCP context
// - ChatGPT search and fetch tools, which are redundant with the standard tools.
func (s *Server) RegisterTools(client *codersdk.Client, opts ...func(*toolsdk.Deps)) error {
if client == nil {
return xerrors.New("client cannot be nil: MCP HTTP server requires authenticated client")
}
// Create tool dependencies
toolDeps, err := toolsdk.NewDeps(client, opts...)
if err != nil {
return xerrors.Errorf("failed to initialize tool dependencies: %w", err)
}
for _, tool := range toolsdk.All {
// the ReportTask tool requires dependencies not available in the remote MCP context
// the ChatGPT search and fetch tools are redundant with the standard tools.
if tool.Name == toolsdk.ToolNameReportTask ||
tool.Name == toolsdk.ToolNameChatGPTSearch || tool.Name == toolsdk.ToolNameChatGPTFetch {
continue
}
RegisterSDKTool(s.mcpServer, tool, toolDeps)
}
return nil
}
// RegisterPrompts registers all MCP prompt templates with the server.
func (s *Server) RegisterPrompts() {
for _, prompt := range toolsdk.AllPrompts {
RegisterSDKPrompt(s.mcpServer, prompt)
}
}
// ChatGPT tools are the search and fetch tools as defined in https://platform.openai.com/docs/mcp.
// We do not expose any extra ones because ChatGPT has an undocumented "Safety Scan" feature.
// In my experiments, if I included extra tools in the MCP server, ChatGPT would often - but not always -
// refuse to add Coder as a connector.
func (s *Server) RegisterChatGPTTools(client *codersdk.Client, opts ...func(*toolsdk.Deps)) error {
if client == nil {
return xerrors.New("client cannot be nil: MCP HTTP server requires authenticated client")
}
// Create tool dependencies
toolDeps, err := toolsdk.NewDeps(client, opts...)
if err != nil {
return xerrors.Errorf("failed to initialize tool dependencies: %w", err)
}
for _, tool := range toolsdk.All {
if tool.Name != toolsdk.ToolNameChatGPTSearch && tool.Name != toolsdk.ToolNameChatGPTFetch {
continue
}
RegisterSDKTool(s.mcpServer, tool, toolDeps)
}
return nil
}
// RegisterSDKTool registers a [toolsdk.GenericTool] with an MCP server.
func RegisterSDKTool(srv *mcp.Server, sdkTool toolsdk.GenericTool, tb toolsdk.Deps) {
if sdkTool.Schema.Properties == nil {
panic("developer error: schema properties cannot be nil")
}
inputSchema := map[string]any{
"type": "object",
"properties": sdkTool.Schema.Properties,
"additionalProperties": false,
}
if len(sdkTool.Schema.Required) > 0 {
inputSchema["required"] = sdkTool.Schema.Required
}
srv.AddTool(&mcp.Tool{
Name: sdkTool.Name,
Description: sdkTool.Description,
InputSchema: inputSchema,
// Set pointer-valued hints even when false so every hint
// remains explicit on the wire.
Annotations: &mcp.ToolAnnotations{
ReadOnlyHint: sdkTool.MCPAnnotations.ReadOnlyHint,
DestructiveHint: new(sdkTool.MCPAnnotations.DestructiveHint),
IdempotentHint: sdkTool.MCPAnnotations.IdempotentHint,
OpenWorldHint: new(sdkTool.MCPAnnotations.OpenWorldHint),
},
}, func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
result, err := sdkTool.Handler(ctx, tb, req.Params.Arguments)
if err != nil {
var validationErr *toolsdk.ArgumentValidationError
if !errors.As(err, &validationErr) {
return toolErrorResult(err.Error()), nil
}
content, marshalErr := json.Marshal(struct {
Error string `json:"error"`
ExpectedSchema map[string]any `json:"expectedSchema"`
}{
Error: validationErr.Error(),
ExpectedSchema: inputSchema,
})
if marshalErr != nil {
return toolErrorResult(xerrors.Errorf("marshal MCP tool argument validation response: %w", marshalErr).Error()), nil
}
return toolErrorResult(string(content)), nil
}
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: string(result)},
},
}, nil
})
}
func toolErrorResult(message string) *mcp.CallToolResult {
return &mcp.CallToolResult{
Content: []mcp.Content{&mcp.TextContent{Text: message}},
IsError: true,
}
}
// RegisterSDKPrompt registers a [toolsdk.Prompt] with an MCP server.
func RegisterSDKPrompt(srv *mcp.Server, sdkPrompt toolsdk.Prompt) {
args := make([]*mcp.PromptArgument, 0, len(sdkPrompt.Arguments))
for _, arg := range sdkPrompt.Arguments {
args = append(args, &mcp.PromptArgument{
Name: arg.Name,
Description: arg.Description,
Required: arg.Required,
})
}
srv.AddPrompt(&mcp.Prompt{
Name: sdkPrompt.Name,
Description: sdkPrompt.Description,
Arguments: args,
}, func(_ context.Context, req *mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
text, err := sdkPrompt.Render(req.Params.Arguments)
if err != nil {
return nil, err
}
return &mcp.GetPromptResult{
Description: sdkPrompt.Description,
Messages: []*mcp.PromptMessage{
{Role: "user", Content: &mcp.TextContent{Text: text}},
},
}, nil
})
}
type slogHandler struct {
logger slog.Logger
}
// The SDK logs several INFO lines per stateless request (session
// connect/disconnect), so only warnings and errors are forwarded.
func (*slogHandler) Enabled(_ context.Context, level stdslog.Level) bool {
return level >= stdslog.LevelWarn
}
func (h *slogHandler) Handle(ctx context.Context, record stdslog.Record) error {
fields := make([]slog.Field, 0, record.NumAttrs())
record.Attrs(func(attr stdslog.Attr) bool {
fields = append(fields, slog.F(attr.Key, attr.Value.Any()))
return true
})
switch {
case record.Level >= stdslog.LevelError:
h.logger.Error(ctx, record.Message, fields...)
case record.Level >= stdslog.LevelWarn:
h.logger.Warn(ctx, record.Message, fields...)
default:
h.logger.Info(ctx, record.Message, fields...)
}
return nil
}
func (h *slogHandler) WithAttrs(attrs []stdslog.Attr) stdslog.Handler {
fields := make([]slog.Field, 0, len(attrs))
for _, attr := range attrs {
fields = append(fields, slog.F(attr.Key, attr.Value.Any()))
}
return &slogHandler{logger: h.logger.With(fields...)}
}
func (h *slogHandler) WithGroup(string) stdslog.Handler {
return h
}