mcp-server

garaekz/mcp-server

3.1

If you are the rightful owner of mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This repository implements a minimal MCP server in Go 1.22+.

Tools
5
Resources
0
Prompts
0

MCP Server

This repository implements a minimal MCP server in Go 1.22+. It exposes a REST/WS gateway for creating agent runs and streaming events, plus a JSON‑RPC over WebSocket interface. It also includes a simple sandboxed runtime for executing tools with configurable limits.

Build

Run make tidy to download dependencies and make build to compile the server binary:

make tidy
make build

The binary will be generated at ./bin/mcpd.

Run

Start the server by specifying an address and sandbox directory. Environment variables may also be used instead of flags.

./bin/mcpd --addr :8080 --sandbox ./data --log-level info --api-key secret

Required flags:

  • --addr – host:port to listen on.
  • --sandbox – directory used as the root of the filesystem sandbox.
  • --log-level – one of debug, info, warn, error.
  • --api-key – API key required for authenticated endpoints.
  • --http-allow-hosts – comma separated list of allowed domains for http.fetch.

Additional environment variables (with defaults):

  • MCP_CORS_ORIGINS – comma separated list of allowed origins for CORS. Empty allows all.
  • MCP_RATE_LIMIT – maximum requests per minute per IP.
  • MCP_RUN_TTL – duration after which a run is evicted, e.g. 10m.
  • MCP_HTTP_MAX_BYTES – maximum response body bytes for http.fetch (default 1048576).
  • MCP_HTTP_ALLOW_HOSTS – comma separated list of allowed domains for http.fetch. If empty, any public host is allowed.
  • MCP_SHELL_ENABLED – set to false to disable shell.run.
  • MCP_SHELL_ALLOW – comma separated allowlist of executables permitted for shell.run.

Endpoints

REST

MethodPathDescription
POST/runsCreates a new run from a prompt.
GET/runs/{id}Returns the current state of a run.
GET/runs/{id}/eventsServer‑sent events stream of run events.
GET/toolsReturns the list of available tool names.
GET/healthzLiveness probe.
GET/readyzReadiness probe.
GET/metricsPrometheus metrics.

All endpoints except /healthz, /readyz and /metrics require an API key. Provide it via the Authorization header as a bearer token or the X-API-Key header.

WebSocket

Connect to /ws with the same API key to use JSON‑RPC 2.0 over WebSocket. Messages are objects with jsonrpc="2.0". Methods correspond to tool names or agent operations. Batch requests are supported. Notifications (requests without an id) do not receive responses.

Example using wscat:

wscat -H "Authorization: Bearer secret" -c ws://localhost:8080/ws
> {"jsonrpc":"2.0","method":"fs.read","params":{"path":"README.md"},"id":1}
< {"jsonrpc":"2.0","id":1,"result":"..."}

Tools

The following tools are built in:

  • fs.read – reads a file from within the sandbox.
  • fs.write – writes a file; requires a confirmation parameter confirm to be true.
  • shell.run – runs a command from an allowlist; can be disabled.
  • http.fetch – performs an HTTP GET with anti‑SSRF checks and returns status, headers and body (up to MCP_HTTP_MAX_BYTES).
  • git.status – returns git status output from within the sandbox (assumes a git repository).

Example run

Create a run via cURL and stream its events:

curl -XPOST http://localhost:8080/runs \
  -H "Authorization: Bearer secret" \
  -d '{"prompt":"Hello, world!"}'

curl http://localhost:8080/runs/123/events -H "Authorization: Bearer secret"

License

This project is licensed under the MIT License. See LICENSE for details.