MESA Core · v0.9.3
MCP entegrasyonu
Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.
İki bağlantı seçeneğini ayırın#
Doğrudan V4 stdio sunucusu ile HTTP geçidi ve yerel köprü farklı biçimde çalışır. Belirli veri kümeleriyle sınırlı köprü, sunucunun verdiği erişim kapsamını korur; tüm sistemi değiştiren yeniden oluşturma işlemini açmaz. Bir aracın kullanılabilir olması, sistemin yetenek bildirimine bağlıdır. MCP kullanmak kimlik doğrulamayı atlamaz veya desteklenmeyen çizge aramasını etkinleştirmez.
Ayrıntılara geçin#
Tam bağlantı kuralları aşağıdaki özgün kaynakta bulunur. Ayrıca mimariyi, API’yi, işletim koşullarını ve sürümün sınırlarını okuyun.
v0.9.3 ile çalışma#
Doğrudan V4 stdio, MCP istemcisinin araç onaylarını ve API anahtarının yetkilerini kullanır; gateway onay/denetimi ayrı bir bağlantıdır. Önce mesa start, sonra mesa mcp-config çalıştırın; üretilen yapılandırmayı özel tutun.
Kaynak belgedeki ilgili bölümler
Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.
MESA MCP exposes MESA through an HTTP gateway and stdio adapters. Antigravity uses a
small stdio bridge which connects to an independently supervised HTTP gateway;
the bridge never imports or accesses storage backends directly.
Prerequisites#
Follow installation and credential provisioning
first. For canonical writes the V4 API needs model-enabled extraction and
embedding; the gateway does not supply missing Core providers. Start that API
and then the MCP gateway. The gateway owns credentials,
policy, approvals, operation state and the connection pool; the bridge owns
only its local encrypted write spool.
The following starts only the gateway, after the API is ready. Supply a real
protected Fernet key in MESA_GATEWAY_ENCRYPTION_KEY and point the control DB
at the same deployment used by the admin CLI:
MESA_BASE_URL=http://127.0.0.1:8000 \
MESA_GATEWAY_CONTROL_DB=/absolute/path/to/mesa-data/mesa.db \
.venv/bin/mesa-mcp-gatewayConnecting Claude Desktop and MCP clients (mesa mcp-config)#
After running mesa start, generate the ready-to-paste MCP server configuration block from your provisioned credentials:
mesa mcp-configThis prints a configuration block using the provisioned credentials and the absolute path to mesa-mcp:
{
"mcpServers": {
"mesa": {
"command": "/absolute/path/to/mesa-mcp",
"env": {
"MESA_BASE_URL": "http://127.0.0.1:8000",
"MESA_API_KEY": "...",
"MESA_TENANT_ID": "local",
"MESA_WORKSPACE_ID": "default",
"MESA_DATASET_ID": "default",
"MESA_ACTOR_ID": "local-agent"
}
}
}
}Add this configuration to your Claude Desktop configuration file (claude_desktop_config.json) to connect Claude directly to MESA.
Codex direct HTTP integration#
Codex connects directly to the durable gateway at http://127.0.0.1:8765/mcp.
The local, gitignored .codex/config.toml contains no credential. Create or
update the trusted project configuration through the local CLI:
.venv/bin/mesa codex install --workspace /absolute/path/to/project \
--control-db /absolute/path/to/mesa.db
.venv/bin/mesa codex doctor --workspace /absolute/path/to/project
.venv/bin/mesa codex run --workspace /absolute/path/to/projectinstall creates or updates a workspace-fingerprint binding, merges only the
MESA-managed config/hook entries and writes a timestamped backup before every
change. Its token and credential ID live only in
$XDG_CONFIG_HOME/mesa/codex/<fingerprint>.env (directory 0700, file 0600).
run is the supported way to give Codex CLI that environment; it never writes
the token into the repository or global desktop environment.
Use mesa codex profile get|set to change the binding’s hook settings and
context limits. Limits never exceed eight memories and 2,500 tokens. Use
mesa codex rotate-token while the gateway is running: it proves the new
credential with an MCP initialize call before replacing the local env file and
revoking the old credential. disable revokes the active credential and
removes the local secret; uninstall also removes only the MESA-managed
project config and hook entries.
Each Codex credential can access only its recorded workspace binding. The
control API returns safe credential summaries and can revoke a credential, but it
never issues or displays plaintext tokens. Codex hooks load bounded project
memory on session start and compaction; they never write transcript content to
memory and do not prevent a session from starting when MESA is unavailable.
Do not commit credentials. The protected environment file must be mode 0600;
the unit file is nonsecret deployment configuration.
For systemd, copy deploy/systemd/mcp-gateway.env.example to
/etc/mesa/mcp-gateway.env, set mode 0600, and use the supplied
mesa-mcp-gateway.service. The unit intentionally obtains all long-lived
gateway secrets from EnvironmentFile; Codex project config contains no secrets.
Every /control/mcp/* call requires an active authenticated principal and the
server-side ADMIN control role, including loopback calls. Localhost
access alone grants no control authority. Use the normal API credential and
an authenticated reverse proxy for remote deployment; see
Operator approval#
Approvals and the control-plane audit are HTTP gateway features. The direct
mesa-mcp stdio server executes tools using the MCP client's tool approval and
the MESA API key's grants; it creates no local database and works from any
working directory. Its bridge transport still forwards calls to the gateway.
Approval and rejection are local gateway control-plane operations. Grant the operator
the existing server-side ADMIN control role, then point the CLI at the same
gateway and RBAC databases used by the running MESA services:
export MESA_STORAGE_ROOT=/absolute/path/to/mesa-data
export MESA_GATEWAY_CONTROL_DB=$MESA_STORAGE_ROOT/mesa.db
export MESA_PRINCIPAL_ID=memory-operator
mesa-v4-admin --policy-db $MESA_STORAGE_ROOT/rbac_policy.db \
grant-control --principal $MESA_PRINCIPAL_ID
mesa operations approve op_012345 --reason "source reviewed"
mesa operations reject op_678901 --reason "insufficient provenance"The commands accept the public operation_id, not the internal approval ID.
They fail closed unless the operation is still PENDING_APPROVAL, its client
and project binding remain active, and the named principal has the control
administrator role. A decision is recorded once with its operator and reason.
The running gateway then claims approved work through its normal approval loop;
rejected work becomes terminal REJECTED and is never dispatched.
Antigravity#
Install Antigravity from the trusted repository root:
.venv/bin/mesa antigravity install --workspace /absolute/path/to/project \
--control-db /absolute/path/to/mesa.db
.venv/bin/mesa antigravity doctor --workspace /absolute/path/to/projectThe install command writes a MESA-managed entry to the local, gitignored
.agents/mcp_config.json without a token. The bridge reads its binding-scoped
credential only from the protected XDG config file. This is a breaking migration: legacy shared
MESA_GATEWAY_TOKEN bridge configurations fail closed until installed again.
Every write tool requires an explicit idempotency_key; stdout remains reserved
for MCP JSON-RPC and logs go to stderr.
Use mesa antigravity profile get|set for the binding’s token-bounded context
profile, and rotate-token, disable or uninstall for its credential
lifecycle.
Tools#
mesa_healthreports bridge, gateway, MESA and spool state, including
DEGRADED operation.
mesa_recallperforms scoped V4 search or token-bounded context retrieval.mesa_remember,mesa_improveandmesa_forgetreturn durable operation
IDs; default policy returns PENDING_APPROVAL rather than holding stdio open.
mesa_get_operation_statuspolls approval and mutation progress.
The bridge fails closed when the client/workspace binding is absent. A repeated
write with the same idempotency key returns the original operation. While the
gateway is briefly unavailable, remember and improve are encrypted and queued
under $XDG_STATE_HOME/mesa; forget is never queued.
Smoke check#
With the same protected environment used by Antigravity:
.venv/bin/python -m mesa_mcp.antigravity_bridgeUse MCP Inspector or Antigravity to initialize the process and call
mesa_health. Do not run it in a terminal expecting human-readable stdout:
stdio is a JSON-RPC protocol stream. mesa_mcp.server uses its
V4 service adapter. Provide MESA_TENANT_ID, MESA_WORKSPACE_ID,
MESA_DATASET_ID, MESA_WORKSPACE_ROOT and an authorized binding/scope.
The supervised gateway is the documented Codex/Antigravity path.
See configuration, control API
and quickstart. The path and operation IDs above are
examples; use the actual deployment values. No automatic transcript saving or
certified legal review is promised.
