Self-hosted Model Context Protocol host on Rails 8 (Ruby 4.0.5, see mise.toml).
The operator UI uses a session login (User). MCP clients authenticate with an ApiKey Bearer token and/or per-instance OAuth 2.1 (PKCE). Each integration is an STI subclass of McpServer under servers/<code>/.
You need Ruby 4.0.5 and config/master.key. The key is not in git (it decrypts config/credentials.yml.enc). Ask the repo owner for it and place it at config/master.key before booting.
cp .env.example .env
bundle install
bin/rails db:prepare
bin/rails db:seed
bin/devbin/dev starts the web server on port 3000, Solid Queue, and the Tailwind watcher. Open http://localhost:3000.
EMCP_PUBLIC_URL defaults to http://localhost:3000 when unset. For OAuth callbacks that must match a public host, set it in .env with no trailing slash.
- Email:
user1@emcp.local - Password:
EMCP_USER1_PASSWORD, oremcp-dev-passwordin development - After seed, the console prints a development ApiKey (
tkn_usr_…) when the user has none - Integrations:
/servers - Contexts (hubs that proxy other servers):
/contexts - Instance auth:
/servers/<id>/auth(numeric instance id, from the servers or contexts list) - Google Sign-In is optional. It appears only when
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETare set. Redirect:${APP_HOST}/auth/google_oauth2/callback
CLI-backed tools (HEY, Basecamp, Google Workspace, 1Password, Home Assistant) call binaries. The Docker image ships them. A local bin/dev process uses whatever is on PATH (HEY_BIN, BASECAMP_BIN, OP_BIN, HASS_CLI_BIN, and gws). WhatsApp’s Go bridge is built from servers/whatsapp/bridge or baked into the image. Telegram’s MTProto bridge is built from servers/telegram/bridge the same way. Apple Reminders uses iCloud CalDAV from the Linux host. An app-specific password is the credential. Lists upgraded to the current Reminders format are not visible on that API.
| Variable | Purpose |
|---|---|
EMCP_PUBLIC_URL |
Public base URL, no trailing slash. OAuth metadata and MCP URLs |
EMCP_USER1_PASSWORD |
Seeded operator password. Development default: emcp-dev-password |
API_KEY_HMAC_SECRET_KEY |
HMAC secret for ApiKey digests. Development falls back to a fixed dev secret |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
Optional Google Sign-In |
APP_HOST |
Optional. Used as the public URL when EMCP_PUBLIC_URL is unset |
WEBHOOK_RETAIN |
Seconds to keep outbound webhook rows. Default 604800 (7 days). PurgeWebhooksJob runs daily |
BROWSER_ALLOW_WRITE |
Enable Browser write tools (click, type, navigate). Default off |
BROWSER_TIMEOUT |
Seconds to wait for the Chrome extension. Default 30 |
BROWSER_ALLOWED_ORIGINS |
Browser allowlist when the instance field is empty. Default https://*/*. Comma-separated Chrome match patterns |
BROWSER_ALLOW_EVAL |
Enable browser_eval_readonly. Default off |
BROWSER_WS_HEARTBEAT |
Seconds between extension heartbeats. Default 15. A silent socket is treated as offline after three intervals |
EMCP_MAX_RESPONSE_BYTES |
Max CLI/stdio bytes returned by a tool call, including context_call_tool. Default 1048576 (1 MiB). Override one server with max_response_bytes under servers.<code> in config/settings.yml, or with <CODE>_MAX_RESPONSE_BYTES. Past the limit the result stays valid JSON and sets truncated, total_bytes, and returned_bytes |
EMCP_MAX_RESPONSE_BYTES |
Max CLI/stdio bytes returned by a tool call, including context_call_tool. Default 1048576 (1 MiB). Override one server with max_response_bytes under servers.<code> in config/settings.yml, or with <CODE>_MAX_RESPONSE_BYTES. Past the limit the result stays valid JSON and sets truncated, total_bytes, and returned_bytes |
EMCP_MAX_RESPONSE_BYTES |
Max CLI/stdio bytes returned by a tool call, including context_call_tool. Default 1048576 (1 MiB). Override one server with max_response_bytes under servers.<code> in config/settings.yml, or with <CODE>_MAX_RESPONSE_BYTES. Past the limit the result stays valid JSON and sets truncated, total_bytes, and returned_bytes |
Per-integration variables are in .env.example and servers/<code>/README.md. Prefer the auth form over putting provider tokens in .env.
Copy the endpoint from /servers. It includes the type code and the instance id:
${EMCP_PUBLIC_URL}/servers/<type_code>/<id>/mcp
A Context is one MCP URL that proxies a bundle of your other servers (house, work, a project). Copy it from /contexts:
${EMCP_PUBLIC_URL}/context/<id>/mcp
Claude, ChatGPT, Cursor, and similar tools are MCP clients. Several of them can attach to the same instance. Use separate instances for isolated credentials (work vs personal, two Fatture companies). Point a client at a Context when it should see a whole bundle through one connector.
ApiKey
User.find_by(email: "user1@emcp.local").api_key!
# => "tkn_usr_..."Send Authorization: Bearer tkn_usr_.... The key authenticates as the instance owner.
OAuth 2.1 discovery, per instance:
/.well-known/oauth-authorization-server/servers/<type_code>/<id>/.well-known/oauth-protected-resource/servers/<type_code>/<id>/mcp
Per context:
/.well-known/oauth-authorization-server/context/<id>/.well-known/oauth-protected-resource/context/<id>/mcp
Provider OAuth callbacks (Fatture in Cloud, X, …) are:
${EMCP_PUBLIC_URL}/servers/<type_code>/<id>/oauth_callback
The auth form prints that URL. Register that exact string with the provider.
- Type (
McpServerType): catalog entry (hey,fattureincloud,context, …). Shared defaults live inconfig/settings.ymlunderservers.<code>. - Instance (
McpServer): one row per user, with its own name, tags, credentials, and MCP URL. Many instances of the same type are allowed. - Context: an instance of type
context. Not seeded byprovision_defaults_for!. Join tablecontext_memberships(activepauses a member without removing it). Nested contexts are forbidden. - One instance is one provider account. Many AI clients can connect to it.
servers/<code>/server.rbregisters withEmcp.register_integration(...).- Instance credentials: encrypted columns plus
storage/mcp/instances/<id>/(server.yml,oauth_token.json). That directory is gitignored. - MCP OAuth clients and tokens:
mcp_oauth_*tables. - Activity logs:
log/<server_code>-<id>.log, kept forSettings.logs.retain_days(default 30).
HEY (CLI 1.10.1), Basecamp (CLI 0.22.1), Fatture in Cloud (API v2), Google Workspace (gws 0.22.5), Toggl Track (API v9), Bluesky, Twitter/X (API v2), TeslaMate, Tessie (API), Home Assistant (hass-cli 1.0.0), 1Password (CLI 2.41.1), WhatsApp (whatsmeow bridge), Telegram (MTProto bridge), Microsoft Graph (SharePoint sites), Shopify (Admin API, one store per instance), Browser (Chrome extension relay), Jethr (employees, payslips, and reports through the signed-in admin tab), Apple Reminders (iCloud CalDAV), Generic (remote MCP proxy, token in a header or query string), Context (hub that proxies other instances). Details are in each servers/*/README.md.
The operator UI splits Servers (/servers) and Contexts (/contexts). The active tab is underlined.
Create a context, open it, attach the servers it should proxy. A Generic server can stand in for a remote MCP such as https://wrks.it/mcp. Pause a membership to keep it listed without exposing tools. Turn the context itself inactive to refuse proxied calls while MCP clients can still connect.
The hub does not flatten child catalogs. Clients call context_list_servers, then context_get_server / context_list_tools, then context_call_tool with the child tool name and arguments. Identify a proxied server by numeric id, instance id (hey-12), or type code when it is unique in that context. See servers/context/README.md.
bin/rails testKamal config is config/deploy.yml. The image downloads the CLI binaries and builds the WhatsApp and Telegram bridges. Production secrets (RAILS_MASTER_KEY, Google OmniAuth) come from .kamal/secrets. Other runtime env can live in /data/emcp/storage/.env on the host volume, loaded at boot and not overriding values already set by Kamal.
The footer (vX.Y.Z · abc1234) is baked into VERSION at image build (GIT_COMMIT / GIT_TAG from the current git HEAD and the highest v* tag). The image does not include .git. A new version number needs a new tag (git tag v1.2.1); the short SHA updates on every deploy.
install -m 600 /dev/stdin /data/emcp/storage/.env < .env