Connect an MCP client

The Dimple MCP server lets an MCP client read and change the memory store. The default setup uses standard input and output, and the client starts the server when it connects.

Before you start

Install the Dimple CLI and create dimple.jsonc with dimple init. Run the MCP server from the directory that holds the configuration file, or pass its path with --config.

Add Dimple to a client

To print a client configuration that includes the current directory, run:

dimple mcp --print

For Codex, add this entry to .codex/config.toml:

[mcp_servers.dimple]
command = "dimple"
args = ["mcp"]

For a client that uses JSON configuration, add this entry:

{
  "mcpServers": {
    "dimple": {
      "command": "dimple",
      "args": ["mcp"]
    }
  }
}

These examples assume that the client starts Dimple in your project directory. If it starts elsewhere, use the cwd value from dimple mcp --print when the client supports it. Restart or reload the client after you save its configuration.

Choose tools for the agent

The server exposes separate tools for memory writes and search, graph review, code indexing, and maintenance. The client can show these tools to the agent and apply its own approval rules.

memory_index accepts explicit paths or changed: true for the git-changed files in the served worktree. Set force: true to re-embed every selected unit. Embeddings run in the background, so the result carries pendingEmbeddings and maintenance_health reports the queue drain.

Narrow the tool surface

The HTTP daemon accepts these opt-in filters. A header wins over the query parameter for the same axis.

Query parameter	Header	Effect
?readonly=1	x-dimple-read-only: 1	Keep read-only tools only; applied after the allowlist.
?tools=memory_get,graph_explain	x-dimple-tools	Keep these tools; docs tools remain available.
?features=memory,graph	x-dimple-features	Keep these feature groups.
?exclude_tools=system_reload	x-dimple-exclude-tools	Drop these tools.

Feature groups are memory, graph, maintenance, system, and docs. Hyphens and underscores are equivalent. tools and features combine as a union, then readonly narrows the result, so a write tool cannot be re-added with ?tools=.

An unknown tool name returns 400 with the valid names. When the configuration has no llm section, maintenance_dream is not advertised.

Some tools change or delete data. Review the client’s tool approval settings before you enable writes, indexing, or maintenance actions.

The server also provides docs_search to find Dimple documentation and open_in_dimple to resolve a tool name to its guide.

Run a local HTTP server

To use an HTTP connection instead of a process over standard input and output, use the managed daemon:

dimple mcp start
dimple mcp status
dimple mcp stop

The daemon listens on 127.0.0.1:8787 by default. It supports Streamable HTTP and stays on the machine.

What the server can access

The server uses the configuration of its process. Local embeddings and local database files stay on the machine. A hosted embedding provider or a remote database can make network requests.

The dimple://config resource masks API keys. Other resources expose memories, neighboring graph records, and health information. The dimple.context and dimple.review prompts provide session context and pending graph decisions.

Next steps

• Quickstart to create a local store.
• Use the CLI for terminal commands.
• Configuration reference for database and provider settings.