Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

docs: document connecting to Open Executive as an MCP server

Rufus2be7d09cb6bc
diff --git a/.env.example b/.env.example
index c81604cd..01c47923 100644
--- a/.env.example
+++ b/.env.example
@@ -222,6 +222,10 @@ GOOGLE_OAUTH_CLIENT_SECRET=
# MCP gateway (the client side — external MCP servers surfaced as Executive
# tools, including the Google Workspace one configured above).
+# NOTE: this is the gateway only. Exposing Open Executive itself AS an MCP
+# server to other agents is a separate feature that needs none of these vars:
+# it is served at /mcp by the API and gated by BACKEND_SHARED_SECRET above.
+# See the "Connect as an MCP Server" section of README.md.
# Left unset, MCP turns itself on when MCP_SERVERS_CONFIG_PATH exists, so
# copying mcp_servers.json.example into place is all that is needed. Set it
# explicitly to override that either way: MCP_ENABLED=false keeps MCP off with
diff --git a/README.md b/README.md
index 9e84b318..1e3242f2 100644
--- a/README.md
+++ b/README.md
@@ -217,6 +217,55 @@ The built-in knowledge base is **trusted by default** — the Executive can use
| **Google Chat** | Mention the app in a space |
| **Discord** | DM the bot, `@mention` it in a channel, or use `/ask` / `/today` slash commands |
| **CLI** | `openexecutive chat` |
+| **MCP** | Point any MCP client at `http://localhost:8000/mcp` (see [Connect as an MCP Server](#connect-as-an-mcp-server)) |
+
+## Connect as an MCP Server
+
+Open Executive exposes its company context and specialist council to external
+MCP clients (Claude Code, Claude Desktop, Cursor, or any other agent), so they
+can ground themselves in your company without being re-briefed. There is no
+separate server process to start: the server is mounted into the FastAPI app at
+`/mcp` over Streamable HTTP, so running the API is running the MCP server.
+
+The endpoint is `http://localhost:8000/mcp`, or `https://<your-host>/mcp` once
+deployed. Authentication is the same shared-secret gate as every other route,
+so clients send `x-api-key: $BACKEND_SHARED_SECRET`. With that variable unset
+locally the gate is off and the header can be omitted.
+
+```json
+{
+ "mcpServers": {
+ "open-executive": {
+ "type": "http",
+ "url": "http://localhost:8000/mcp",
+ "headers": {
+ "x-api-key": "YOUR_BACKEND_SHARED_SECRET"
+ }
+ }
+ }
+}
+```
+
+Claude Code can write that entry for you:
+
+```bash
+claude mcp add --transport http open-executive http://localhost:8000/mcp \
+ --header "x-api-key: YOUR_BACKEND_SHARED_SECRET"
+```
+
+Connected clients get eight read-only resources (company profile, today's
+briefing and activity, people roster, department state, and episodic memory for
+decisions, initiatives and advice) and four tools, of which `consult_specialist`
+is the primary one: domain analysis from any of the nine specialists, each
+grounded in your company's knowledge base. The full inventory is on the **MCP
+Server** section of the `/architecture` page.
+
+This is the inverse of the `MCP_ENABLED` and `MCP_SERVERS_CONFIG_PATH` settings
+under [Configuration](#configuration), which configure the MCP *gateway*: Open
+Executive consuming other servers' tools. The server side needs no configuration
+beyond `BACKEND_SHARED_SECRET`. If a client errors on connect, try `/mcp/` with
+the trailing slash, since the endpoint 307-redirects and not every client
+follows the redirect.
## Document Upload