Add an MCP server for askgod at <askgod_server_address>/mcp.

It has only one tool: Submit a flag.
The MCP server is disabled by default and can be enabled with `mcp: true` in the askgod config.
Internally, it uses the REST method calls to limit code duplication to a minimum.

Signed-off-by: Émilio Gonzalez <little.moon6016@fastmail.com>

Author: Res260

README.md

@@ -47,4 +47,10 @@ This will create two executables in `./bin/linux`: `askgod` and `askgod-server`.
 
 ```bash
 ./bin/linux/askgod-server ./askgod.yaml.example
-```
+```
+
+## MCP Server
+
+The askgod server supports an MCP server at `<askgod_server_address>/mcp`.
+This MCP server allows users to submit flags.
+The MCP Server is disabled by default, but can be enabled by setting `mcp: true` in the config.

api/config.go

@@ -9,6 +9,7 @@ type Config struct {
 
 	Daemon   ConfigDaemon   `json:"daemon"   yaml:"daemon"`
 	Database ConfigDatabase `json:"database" yaml:"database"`
+	MCP      bool           `json:"mcp"      yaml:"mcp"`
 }
 
 // ConfigPut represents the editable Askgod configuration.

askgod.yaml.example

@@ -95,3 +95,6 @@ subnets:
   guests:
     - ::/0
     - 0.0.0.0/0
+
+# Enable or disable the MCP server. Defaults to false.
+mcp: true

internal/mcp/mcp.go

@@ -0,0 +1,169 @@
+// Package mcp implements an MCP server using Streamable HTTP transport.
+package mcp
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+
+	"github.com/inconshreveable/log15"
+)
+
+// MCP implements an MCP server using Streamable HTTP transport.
+type MCP struct {
+	logger  log15.Logger
+	handler http.Handler
+}
+
+// NewMCP creates a new MCP server instance.
+func NewMCP(handler http.Handler, logger log15.Logger) *MCP {
+	return &MCP{
+		handler: handler,
+		logger:  logger,
+	}
+}
+
+// ServeHTTP handles incoming MCP requests over Streamable HTTP.
+func (m *MCP) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
+
+		return
+	}
+
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+
+		return
+	}
+
+	var req Request
+
+	err = json.Unmarshal(body, &req)
+	if err != nil {
+		m.writeError(w, nil, -32700, "Parse error")
+
+		return
+	}
+
+	// Notifications have no id — respond with 202 Accepted.
+	if req.ID == nil {
+		w.WriteHeader(http.StatusAccepted)
+
+		return
+	}
+
+	var id any
+
+	err = json.Unmarshal(*req.ID, &id)
+	if err != nil {
+		id = nil
+	}
+
+	switch req.Method {
+	case "initialize":
+		m.handleInitialize(w, id)
+	case "tools/list":
+		m.handleToolsList(w, id)
+	case "tools/call":
+		m.handleToolsCall(w, r, id, req.Params)
+	default:
+		m.writeError(w, id, -32601, "Method not found")
+	}
+}
+
+func (m *MCP) handleInitialize(w http.ResponseWriter, id any) {
+	result := InitializeResult{
+		ProtocolVersion: "2025-03-26",
+		Capabilities: Capabilities{
+			Tools: &ToolsCapability{},
+		},
+		ServerInfo: ServerInfo{
+			Name:    "askgod",
+			Version: "1.0.0",
+		},
+	}
+
+	m.writeResult(w, id, result)
+}
+
+func (m *MCP) handleToolsList(w http.ResponseWriter, id any) {
+	result := ListToolsResult{
+		Tools: []Tool{
+			{
+				Name:        "submit_flag",
+				Description: "Submit a CTF flag for your team. Returns whether the flag was valid, already submitted, or invalid.",
+				InputSchema: ToolInputSchema{
+					Type: "object",
+					Properties: map[string]any{
+						"flag": map[string]any{
+							"type":        "string",
+							"description": "The flag string to submit",
+						},
+					},
+					Required: []string{"flag"},
+				},
+			},
+		},
+	}
+
+	m.writeResult(w, id, result)
+}
+
+func (m *MCP) handleToolsCall(w http.ResponseWriter, r *http.Request, id any, params json.RawMessage) {
+	var p CallToolParams
+
+	err := json.Unmarshal(params, &p)
+	if err != nil {
+		m.writeError(w, id, -32602, "Invalid params")
+
+		return
+	}
+
+	var result CallToolResult
+
+	switch p.Name {
+	case "submit_flag":
+		result = m.submitFlag(r, p.Arguments)
+	default:
+		m.writeError(w, id, -32602, "Unknown tool: "+p.Name)
+
+		return
+	}
+
+	m.writeResult(w, id, result)
+}
+
+func (m *MCP) writeResult(w http.ResponseWriter, id any, result any) {
+	resp := Response{
+		JSONRPC: "2.0",
+		ID:      id,
+		Result:  result,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	err := json.NewEncoder(w).Encode(resp)
+	if err != nil {
+		m.logger.Error("Failed to encode response", log15.Ctx{"error": err})
+	}
+}
+
+func (m *MCP) writeError(w http.ResponseWriter, id any, code int, message string) {
+	resp := Response{
+		JSONRPC: "2.0",
+		ID:      id,
+		Error: &Error{
+			Code:    code,
+			Message: message,
+		},
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	err := json.NewEncoder(w).Encode(resp)
+	if err != nil {
+		m.logger.Error("Failed to encode error response", log15.Ctx{"error": err})
+	}
+}

internal/mcp/protocol.go

@@ -0,0 +1,83 @@
+package mcp
+
+import "encoding/json"
+
+// Request is a JSON-RPC 2.0 request.
+type Request struct {
+	JSONRPC string           `json:"jsonrpc"`
+	ID      *json.RawMessage `json:"id,omitempty"`
+	Method  string           `json:"method"`
+	Params  json.RawMessage  `json:"params,omitempty"`
+}
+
+// Response is a JSON-RPC 2.0 response.
+type Response struct {
+	JSONRPC string `json:"jsonrpc"`
+	ID      any    `json:"id"`
+	Result  any    `json:"result,omitempty"`
+	Error   *Error `json:"error,omitempty"`
+}
+
+// Error is a JSON-RPC 2.0 error.
+type Error struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+// InitializeResult is the result of an MCP initialize request.
+type InitializeResult struct {
+	ProtocolVersion string       `json:"protocolVersion"` //nolint:tagliatelle
+	Capabilities    Capabilities `json:"capabilities"`
+	ServerInfo      ServerInfo   `json:"serverInfo"` //nolint:tagliatelle
+}
+
+// Capabilities describes what the server supports.
+type Capabilities struct {
+	Tools *ToolsCapability `json:"tools,omitempty"`
+}
+
+// ToolsCapability indicates the server supports tools.
+type ToolsCapability struct{}
+
+// ServerInfo holds the server name and version.
+type ServerInfo struct {
+	Name    string `json:"name"`
+	Version string `json:"version"`
+}
+
+// Tool is a tool available on the server.
+type Tool struct {
+	Name        string          `json:"name"`
+	Description string          `json:"description"`
+	InputSchema ToolInputSchema `json:"inputSchema"` //nolint:tagliatelle
+}
+
+// ToolInputSchema is a JSON Schema object describing the tool's parameters.
+type ToolInputSchema struct {
+	Type       string         `json:"type"`
+	Properties map[string]any `json:"properties,omitempty"`
+	Required   []string       `json:"required,omitempty"`
+}
+
+// CallToolParams holds the parameters for a tools/call request.
+type CallToolParams struct {
+	Name      string         `json:"name"`
+	Arguments map[string]any `json:"arguments,omitempty"`
+}
+
+// CallToolResult holds the result of a tool call.
+type CallToolResult struct {
+	Content []Content `json:"content"`
+	IsError bool      `json:"isError,omitempty"` //nolint:tagliatelle
+}
+
+// Content is a content block in a tool result.
+type Content struct {
+	Type string `json:"type"`
+	Text string `json:"text"`
+}
+
+// ListToolsResult holds the result of a tools/list request.
+type ListToolsResult struct {
+	Tools []Tool `json:"tools"`
+}

internal/mcp/tools.go

@@ -0,0 +1,53 @@
+package mcp
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/nsec/askgod/api"
+)
+
+func (m *MCP) submitFlag(r *http.Request, args map[string]any) CallToolResult {
+	flagStr, ok := args["flag"].(string)
+	if !ok || flagStr == "" {
+		return errorResult("Missing or invalid 'flag' argument")
+	}
+
+	body, err := json.Marshal(api.FlagPost{Flag: flagStr, AIAgent: true})
+	if err != nil {
+		return errorResult("Internal server error")
+	}
+
+	req, _ := http.NewRequestWithContext(r.Context(), http.MethodPost, "/1.0/team/flags", bytes.NewReader(body))
+	req.RemoteAddr = r.RemoteAddr
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	m.handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		return errorResult(strings.TrimSpace(rec.Body.String()))
+	}
+
+	var result api.Flag
+
+	err = json.NewDecoder(rec.Body).Decode(&result)
+	if err != nil {
+		return errorResult("Internal server error")
+	}
+
+	msg := fmt.Sprintf("Correct flag! +%d points\n", result.Value)
+	if result.ReturnString != "" {
+		msg += fmt.Sprintf("Return message: %s\n", result.ReturnString)
+	}
+
+	return CallToolResult{Content: []Content{{Type: "text", Text: msg}}}
+}
+
+func errorResult(msg string) CallToolResult {
+	return CallToolResult{Content: []Content{{Type: "text", Text: msg}}, IsError: true}
+}

internal/rest/attach.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/nsec/askgod/internal/config"
 	"github.com/nsec/askgod/internal/database"
+	"github.com/nsec/askgod/internal/mcp"
 )
 
 var clusterPeers []string
@@ -56,6 +57,16 @@ func AttachFunctions(ctx context.Context, conf *config.Config, router *http.Serv
 	r.registerEndpoint("/1.0/teams", "admin", r.adminGetTeams, r.adminCreateTeam, nil, r.adminClearTeams)
 	r.registerEndpoint("/1.0/teams/{id}", "admin", r.adminGetTeam, nil, r.adminUpdateTeam, r.adminDeleteTeam)
 
+	// MCP server endpoint (disabled by default)
+	if conf.MCP {
+		r.logger.Info("Starting the MCP server")
+		mcpServer := mcp.NewMCP(r.router, logger.New("component", "mcp"))
+
+		r.registerEndpoint("/mcp", "team", nil, func(writer http.ResponseWriter, request *http.Request, _ log15.Logger) {
+			mcpServer.ServeHTTP(writer, request)
+		}, nil, nil)
+	}
+
 	// Setup forwarder
 	for _, peer := range conf.Daemon.ClusterPeers {
 		u, err := url.ParseRequestURI(peer)