MESA Core · v0.9.3

MCP entegrasyonu

v0.9.3 kaynak: README_MCP.md

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.

Dayanak kaynaklar
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:

bash
MESA_BASE_URL=http://127.0.0.1:8000 \
MESA_GATEWAY_CONTROL_DB=/absolute/path/to/mesa-data/mesa.db \
.venv/bin/mesa-mcp-gateway

Connecting 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:

bash
mesa mcp-config

This prints a configuration block using the provisioned credentials and the absolute path to mesa-mcp:

json
{
  "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:

bash
.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/project

install 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

control API authorization.

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:

bash
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:

bash
.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/project

The 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_health reports bridge, gateway, MESA and spool state, including

DEGRADED operation.

  • mesa_recall performs scoped V4 search or token-bounded context retrieval.
  • mesa_remember, mesa_improve and mesa_forget return durable operation

IDs; default policy returns PENDING_APPROVAL rather than holding stdio open.

  • mesa_get_operation_status polls 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:

bash
.venv/bin/python -m mesa_mcp.antigravity_bridge

Use 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.