Misc MCP Server

A standalone MCP server with OAuth auth, separate from the gdata KV store servers. Intended as a home for miscellaneous utility tools that don't belong in the notes KV store. Extensible — add tools to misc_mcp_server.py as needed.

Status

- Server: running on gravlax (systemd: misc-mcp-server.service)
- claude.ai connector: NOT YET SET UP — needs adding at claude.ai settings with URL https://www.critchley.biz/misc/mcp
- Password: stored in ~/.pw_secret_misc on gravlax
- Git: john-critchley/gdata-server, branch m, file misc_mcp_server.py

Architecture

misc_mcp_server.py lives in /home/john/py/gdata-server/ alongside gdata_mcp_server.py. It imports gdata_oauth for all OAuth/auth functionality — no auth code of its own. Runs two uvicorn servers in one process:

- REST/OAuth server on port 8220 — serves OAuth endpoints only (no KV store, no notes_web)
- MCP server on port 8223 — SSE and Streamable HTTP transports

Both transports are controlled by MCP_SSE and MCP_STREAMABLE env vars (both default true).

Ports and Access

Internal (localhost only):
- REST/OAuth: 127.0.0.1:8220
- MCP: 127.0.0.1:8223

External via stunnel TLS:
- REST: gravlax.critchley.biz:18221
- MCP: gravlax.critchley.biz:18223

Via Apache (www.critchley.biz):
- MCP endpoint: https://www.critchley.biz/misc/mcp
- OAuth authorize: https://www.critchley.biz/misc/oauth/authorize
- OAuth token: https://www.critchley.biz/misc/oauth/token
- OAuth register: https://www.critchley.biz/misc/oauth/register
- Discovery: https://www.critchley.biz/.well-known/oauth-authorization-server/misc

OAuth / Auth

- OAUTH_ISSUER: https://www.critchley.biz/misc
- Env file: /etc/gdata_oauth_misc.env (root-readable only)
- Token file: /home/john/.oauth_tokens_misc.json
- Password: ~/.pw_secret_misc on gravlax (save in passwordsafe)
- Login page title: "Authorise misc access" (username field shows "misc" for Firefox password saving)

Systemd

Service: misc-mcp-server.service
User: john
WorkingDirectory: /home/john/py/gdata-server
EnvironmentFile: /etc/gdata_oauth_misc.env

Commands:
- sudo systemctl status misc-mcp-server
- sudo systemctl restart misc-mcp-server
- sudo journalctl -u misc-mcp-server -f

Store Name / Tool Prefix

--name misc (also GDATA_STORE_NAME=misc). All tool descriptions are prefixed [misc store]. The X-MCP-Store: misc header is set on all REST responses.

Adding New Tools

Edit misc_mcp_server.py. In _make_tool_server(), add a types.Tool entry to the list in list_tools(), and add a handler branch in call_tool(). Restart the service. No other changes needed for simple tools.

See: misc-server/tools

Relation to gdata-server

Both servers share gdata_oauth.py and live in the same git repo (john-critchley/gdata-server). The misc server does not use gdata.py or the GDBM database at all. It is a pure MCP server.

Port scheme: public gdata = 8020/8023, private gdata = 8120/8123, misc = 8220/8223 (each +100).