docs(standards): add MCP setup page covering all clients and servers
All checks were successful
continuous-integration/drone/push Build is passing
All checks were successful
continuous-integration/drone/push Build is passing
New wiki page documents the ten per-repo MCP servers (standards + libraries, ports 8001-8010) and per-client config for Claude Code, Codex, Antigravity, OpenCode, and PyCharm, each with linked localhost / mcp.aetoskia.com tabs.
This commit is contained in:
@@ -70,5 +70,7 @@ nav:
|
||||
- Overview: 01_overview.md
|
||||
- App Components: 02_components.md
|
||||
- Start an App: 03_start_an_app.md
|
||||
- MCP:
|
||||
- Setup: 05_mcp_setup.md
|
||||
- Testing & Quality: 04_development/01_testing.md
|
||||
- Releasing & Versioning: 04_development/02_releasing.md
|
||||
338
standards/src/wiki/05_mcp_setup.md
Normal file
338
standards/src/wiki/05_mcp_setup.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# 🔌 MCP Setup
|
||||
|
||||
Every repository ships its documentation as a **Model Context Protocol (MCP)**
|
||||
server, and the `standards` registry server ties them together. The `docs`
|
||||
portal runs each one as a FastMCP **streamable-http** app bound to
|
||||
`0.0.0.0:<port>`, exposing the endpoint at `/mcp` (see `docs/main.py` and
|
||||
`docs/config.yml`).
|
||||
|
||||
Connect your agent to the **`standards`** server first: it answers
|
||||
`find_library`, `list_repos`, and the `start_app` prompt, so the agent reaches
|
||||
for an internal library instead of reimplementing one (see the
|
||||
[Library Registry](../lib/13_library_registry/)).
|
||||
|
||||
---
|
||||
|
||||
## ▶️ Run the servers locally
|
||||
|
||||
From the `docs` checkout:
|
||||
|
||||
```bash
|
||||
.venv\Scripts\python.exe main.py # every server
|
||||
.venv\Scripts\python.exe main.py --servers standards # just the registry
|
||||
```
|
||||
|
||||
`:8000` is the health endpoint (`GET /healthz`), **not** an MCP server.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Servers
|
||||
|
||||
| Slug | MCP server | Port | localhost | mcp.aetoskia.com |
|
||||
|------|------------|------|-----------|------------------|
|
||||
| `standards` | `standards` | 8009 | `http://localhost:8009/mcp` | `https://mcp.aetoskia.com/standards/mcp` |
|
||||
| `doc-forge` | `docforge` | 8001 | `http://localhost:8001/mcp` | `https://mcp.aetoskia.com/doc-forge/mcp` |
|
||||
| `mail-intake` | `mail_intake` | 8002 | `http://localhost:8002/mcp` | `https://mcp.aetoskia.com/mail-intake/mcp` |
|
||||
| `omniread` | `omniread` | 8003 | `http://localhost:8003/mcp` | `https://mcp.aetoskia.com/omniread/mcp` |
|
||||
| `openapi-first` | `openapi_first` | 8004 | `http://localhost:8004/mcp` | `https://mcp.aetoskia.com/openapi-first/mcp` |
|
||||
| `py-jwt` | `jwtlib` | 8005 | `http://localhost:8005/mcp` | `https://mcp.aetoskia.com/py-jwt/mcp` |
|
||||
| `dagpipe` | `dagpipe` | 8006 | `http://localhost:8006/mcp` | `https://mcp.aetoskia.com/dagpipe/mcp` |
|
||||
| `mongo-ops` | `mongo_ops` | 8007 | `http://localhost:8007/mcp` | `https://mcp.aetoskia.com/mongo-ops/mcp` |
|
||||
| `hexa` | `hexa` | 8008 | `http://localhost:8008/mcp` | `https://mcp.aetoskia.com/hexa/mcp` |
|
||||
| `doc-weaver` | `doc-weaver` | 8010 | `http://localhost:8010/mcp` | `https://mcp.aetoskia.com/doc-weaver/mcp` |
|
||||
|
||||
The hosted endpoints are served over HTTPS at `https://mcp.aetoskia.com/<slug>/mcp`.
|
||||
The tabs below are linked (`content.tabs.link`): switching one switches all of
|
||||
them. Every snippet registers **all ten** servers, so a single paste is enough.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Claude Code
|
||||
|
||||
Project-scoped `.mcp.json` at the repo root. The `type` field is required — an
|
||||
entry with a `url` but no `type` is read as a stdio server and skipped.
|
||||
|
||||
=== "localhost"
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"standards": { "type": "http", "url": "http://localhost:8009/mcp" },
|
||||
"doc-forge": { "type": "http", "url": "http://localhost:8001/mcp" },
|
||||
"mail-intake": { "type": "http", "url": "http://localhost:8002/mcp" },
|
||||
"omniread": { "type": "http", "url": "http://localhost:8003/mcp" },
|
||||
"openapi-first": { "type": "http", "url": "http://localhost:8004/mcp" },
|
||||
"py-jwt": { "type": "http", "url": "http://localhost:8005/mcp" },
|
||||
"dagpipe": { "type": "http", "url": "http://localhost:8006/mcp" },
|
||||
"mongo-ops": { "type": "http", "url": "http://localhost:8007/mcp" },
|
||||
"hexa": { "type": "http", "url": "http://localhost:8008/mcp" },
|
||||
"doc-weaver": { "type": "http", "url": "http://localhost:8010/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
=== "mcp.aetoskia.com"
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"standards": { "type": "http", "url": "https://mcp.aetoskia.com/standards/mcp" },
|
||||
"doc-forge": { "type": "http", "url": "https://mcp.aetoskia.com/doc-forge/mcp" },
|
||||
"mail-intake": { "type": "http", "url": "https://mcp.aetoskia.com/mail-intake/mcp" },
|
||||
"omniread": { "type": "http", "url": "https://mcp.aetoskia.com/omniread/mcp" },
|
||||
"openapi-first": { "type": "http", "url": "https://mcp.aetoskia.com/openapi-first/mcp" },
|
||||
"py-jwt": { "type": "http", "url": "https://mcp.aetoskia.com/py-jwt/mcp" },
|
||||
"dagpipe": { "type": "http", "url": "https://mcp.aetoskia.com/dagpipe/mcp" },
|
||||
"mongo-ops": { "type": "http", "url": "https://mcp.aetoskia.com/mongo-ops/mcp" },
|
||||
"hexa": { "type": "http", "url": "https://mcp.aetoskia.com/hexa/mcp" },
|
||||
"doc-weaver": { "type": "http", "url": "https://mcp.aetoskia.com/doc-weaver/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or add them with the CLI:
|
||||
`claude mcp add --transport http standards http://localhost:8009/mcp`.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Codex
|
||||
|
||||
`~/.codex/config.toml` (or a project-scoped `.codex/config.toml`).
|
||||
|
||||
=== "localhost"
|
||||
|
||||
```toml
|
||||
[mcp_servers.standards]
|
||||
url = "http://localhost:8009/mcp"
|
||||
|
||||
[mcp_servers.doc-forge]
|
||||
url = "http://localhost:8001/mcp"
|
||||
|
||||
[mcp_servers.mail-intake]
|
||||
url = "http://localhost:8002/mcp"
|
||||
|
||||
[mcp_servers.omniread]
|
||||
url = "http://localhost:8003/mcp"
|
||||
|
||||
[mcp_servers.openapi-first]
|
||||
url = "http://localhost:8004/mcp"
|
||||
|
||||
[mcp_servers.py-jwt]
|
||||
url = "http://localhost:8005/mcp"
|
||||
|
||||
[mcp_servers.dagpipe]
|
||||
url = "http://localhost:8006/mcp"
|
||||
|
||||
[mcp_servers.mongo-ops]
|
||||
url = "http://localhost:8007/mcp"
|
||||
|
||||
[mcp_servers.hexa]
|
||||
url = "http://localhost:8008/mcp"
|
||||
|
||||
[mcp_servers.doc-weaver]
|
||||
url = "http://localhost:8010/mcp"
|
||||
```
|
||||
|
||||
=== "mcp.aetoskia.com"
|
||||
|
||||
```toml
|
||||
[mcp_servers.standards]
|
||||
url = "https://mcp.aetoskia.com/standards/mcp"
|
||||
|
||||
[mcp_servers.doc-forge]
|
||||
url = "https://mcp.aetoskia.com/doc-forge/mcp"
|
||||
|
||||
[mcp_servers.mail-intake]
|
||||
url = "https://mcp.aetoskia.com/mail-intake/mcp"
|
||||
|
||||
[mcp_servers.omniread]
|
||||
url = "https://mcp.aetoskia.com/omniread/mcp"
|
||||
|
||||
[mcp_servers.openapi-first]
|
||||
url = "https://mcp.aetoskia.com/openapi-first/mcp"
|
||||
|
||||
[mcp_servers.py-jwt]
|
||||
url = "https://mcp.aetoskia.com/py-jwt/mcp"
|
||||
|
||||
[mcp_servers.dagpipe]
|
||||
url = "https://mcp.aetoskia.com/dagpipe/mcp"
|
||||
|
||||
[mcp_servers.mongo-ops]
|
||||
url = "https://mcp.aetoskia.com/mongo-ops/mcp"
|
||||
|
||||
[mcp_servers.hexa]
|
||||
url = "https://mcp.aetoskia.com/hexa/mcp"
|
||||
|
||||
[mcp_servers.doc-weaver]
|
||||
url = "https://mcp.aetoskia.com/doc-weaver/mcp"
|
||||
```
|
||||
|
||||
Or add them with the CLI:
|
||||
`codex mcp add standards --url http://localhost:8009/mcp`.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Antigravity
|
||||
|
||||
`~/.gemini/antigravity/mcp_config.json` (IDE) or
|
||||
`~/.gemini/config/mcp_config.json` (CLI). Antigravity uses **`serverUrl`**, not
|
||||
`url`, for HTTP endpoints.
|
||||
|
||||
=== "localhost"
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"standards": { "serverUrl": "http://localhost:8009/mcp" },
|
||||
"doc-forge": { "serverUrl": "http://localhost:8001/mcp" },
|
||||
"mail-intake": { "serverUrl": "http://localhost:8002/mcp" },
|
||||
"omniread": { "serverUrl": "http://localhost:8003/mcp" },
|
||||
"openapi-first": { "serverUrl": "http://localhost:8004/mcp" },
|
||||
"py-jwt": { "serverUrl": "http://localhost:8005/mcp" },
|
||||
"dagpipe": { "serverUrl": "http://localhost:8006/mcp" },
|
||||
"mongo-ops": { "serverUrl": "http://localhost:8007/mcp" },
|
||||
"hexa": { "serverUrl": "http://localhost:8008/mcp" },
|
||||
"doc-weaver": { "serverUrl": "http://localhost:8010/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
=== "mcp.aetoskia.com"
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"standards": { "serverUrl": "https://mcp.aetoskia.com/standards/mcp" },
|
||||
"doc-forge": { "serverUrl": "https://mcp.aetoskia.com/doc-forge/mcp" },
|
||||
"mail-intake": { "serverUrl": "https://mcp.aetoskia.com/mail-intake/mcp" },
|
||||
"omniread": { "serverUrl": "https://mcp.aetoskia.com/omniread/mcp" },
|
||||
"openapi-first": { "serverUrl": "https://mcp.aetoskia.com/openapi-first/mcp" },
|
||||
"py-jwt": { "serverUrl": "https://mcp.aetoskia.com/py-jwt/mcp" },
|
||||
"dagpipe": { "serverUrl": "https://mcp.aetoskia.com/dagpipe/mcp" },
|
||||
"mongo-ops": { "serverUrl": "https://mcp.aetoskia.com/mongo-ops/mcp" },
|
||||
"hexa": { "serverUrl": "https://mcp.aetoskia.com/hexa/mcp" },
|
||||
"doc-weaver": { "serverUrl": "https://mcp.aetoskia.com/doc-weaver/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 OpenCode
|
||||
|
||||
`opencode.json` (project) or `~/.config/opencode/opencode.json` (global).
|
||||
|
||||
=== "localhost"
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"standards": { "type": "remote", "url": "http://localhost:8009/mcp", "enabled": true },
|
||||
"doc-forge": { "type": "remote", "url": "http://localhost:8001/mcp", "enabled": true },
|
||||
"mail-intake": { "type": "remote", "url": "http://localhost:8002/mcp", "enabled": true },
|
||||
"omniread": { "type": "remote", "url": "http://localhost:8003/mcp", "enabled": true },
|
||||
"openapi-first": { "type": "remote", "url": "http://localhost:8004/mcp", "enabled": true },
|
||||
"py-jwt": { "type": "remote", "url": "http://localhost:8005/mcp", "enabled": true },
|
||||
"dagpipe": { "type": "remote", "url": "http://localhost:8006/mcp", "enabled": true },
|
||||
"mongo-ops": { "type": "remote", "url": "http://localhost:8007/mcp", "enabled": true },
|
||||
"hexa": { "type": "remote", "url": "http://localhost:8008/mcp", "enabled": true },
|
||||
"doc-weaver": { "type": "remote", "url": "http://localhost:8010/mcp", "enabled": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
=== "mcp.aetoskia.com"
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"standards": { "type": "remote", "url": "https://mcp.aetoskia.com/standards/mcp", "enabled": true },
|
||||
"doc-forge": { "type": "remote", "url": "https://mcp.aetoskia.com/doc-forge/mcp", "enabled": true },
|
||||
"mail-intake": { "type": "remote", "url": "https://mcp.aetoskia.com/mail-intake/mcp", "enabled": true },
|
||||
"omniread": { "type": "remote", "url": "https://mcp.aetoskia.com/omniread/mcp", "enabled": true },
|
||||
"openapi-first": { "type": "remote", "url": "https://mcp.aetoskia.com/openapi-first/mcp", "enabled": true },
|
||||
"py-jwt": { "type": "remote", "url": "https://mcp.aetoskia.com/py-jwt/mcp", "enabled": true },
|
||||
"dagpipe": { "type": "remote", "url": "https://mcp.aetoskia.com/dagpipe/mcp", "enabled": true },
|
||||
"mongo-ops": { "type": "remote", "url": "https://mcp.aetoskia.com/mongo-ops/mcp", "enabled": true },
|
||||
"hexa": { "type": "remote", "url": "https://mcp.aetoskia.com/hexa/mcp", "enabled": true },
|
||||
"doc-weaver": { "type": "remote", "url": "https://mcp.aetoskia.com/doc-weaver/mcp", "enabled": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or add them with the CLI:
|
||||
`opencode mcp add standards --url http://localhost:8009/mcp --global`.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 PyCharm (Junie / AI Assistant)
|
||||
|
||||
`~/.junie/mcp/mcp.json` (user scope) or `.junie/mcp/mcp.json` (project scope).
|
||||
The same config is reachable from **Settings | Tools | MCP Server → Manual
|
||||
Client Configuration → Copy HTTP Stream Config**.
|
||||
|
||||
=== "localhost"
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"standards": { "url": "http://localhost:8009/mcp" },
|
||||
"doc-forge": { "url": "http://localhost:8001/mcp" },
|
||||
"mail-intake": { "url": "http://localhost:8002/mcp" },
|
||||
"omniread": { "url": "http://localhost:8003/mcp" },
|
||||
"openapi-first": { "url": "http://localhost:8004/mcp" },
|
||||
"py-jwt": { "url": "http://localhost:8005/mcp" },
|
||||
"dagpipe": { "url": "http://localhost:8006/mcp" },
|
||||
"mongo-ops": { "url": "http://localhost:8007/mcp" },
|
||||
"hexa": { "url": "http://localhost:8008/mcp" },
|
||||
"doc-weaver": { "url": "http://localhost:8010/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
=== "mcp.aetoskia.com"
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"standards": { "url": "https://mcp.aetoskia.com/standards/mcp" },
|
||||
"doc-forge": { "url": "https://mcp.aetoskia.com/doc-forge/mcp" },
|
||||
"mail-intake": { "url": "https://mcp.aetoskia.com/mail-intake/mcp" },
|
||||
"omniread": { "url": "https://mcp.aetoskia.com/omniread/mcp" },
|
||||
"openapi-first": { "url": "https://mcp.aetoskia.com/openapi-first/mcp" },
|
||||
"py-jwt": { "url": "https://mcp.aetoskia.com/py-jwt/mcp" },
|
||||
"dagpipe": { "url": "https://mcp.aetoskia.com/dagpipe/mcp" },
|
||||
"mongo-ops": { "url": "https://mcp.aetoskia.com/mongo-ops/mcp" },
|
||||
"hexa": { "url": "https://mcp.aetoskia.com/hexa/mcp" },
|
||||
"doc-weaver": { "url": "https://mcp.aetoskia.com/doc-weaver/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verify
|
||||
|
||||
- Health check: `curl http://localhost:8000/healthz` → `ok`.
|
||||
- Claude Code: `claude mcp list` → each server … `✓ Connected`.
|
||||
- Codex: `codex mcp list` → each server … `http`.
|
||||
- OpenCode: `opencode mcp list` → each server … `connected`.
|
||||
- In-session: run `/mcp` to list the connected servers and their tools.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Reference
|
||||
|
||||
- [Library Registry](../lib/13_library_registry/) — the catalog each server
|
||||
mirrors, and where `find_library` resolves
|
||||
- [Start an App](03_start_an_app.md) — connect `standards`, then invoke
|
||||
`start_app`
|
||||
- [App Components](02_components.md) — the component model
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Start an App](03_start_an_app.md) · [Testing & Quality](04_development/01_testing.md) · [Library Registry](../lib/13_library_registry/)
|
||||
Reference in New Issue
Block a user