LangMCP

Read-only MCP server for inspecting LangGraph checkpoints, thread state, and long-term memory.

LangMCP helps you answer the debugging question that traces do not always answer:

> What is actually saved in my LangGraph persistence layer right now?

It is not a generic SQL MCP. It uses LangGraph-native checkpointer and store APIs,

connects through named profiles, and keeps database credentials out of tool

arguments.

Why LangMCP

When a stateful agent behaves strangely, the problem is often not only the prompt.

It might be the checkpoint it resumed from, the user ID in configurable state, the

store namespace used for memory, or an oversized message history.

LangMCP gives MCP clients such as Cursor and Claude Desktop a safe inspection

surface for those questions.

Use LangSmith for traces, LangGraph Studio for visual graph workflows, and

LangMCP when you want an assistant in your editor to inspect persisted state

through a narrow read-only interface.

Features

• Profile-based config with environment variable expansion.
• Read-only enforcement in v0.1.
• Secret redaction in health checks and error output.
• PostgreSQL, SQLite, and Redis checkpointer inspection.
• PostgreSQL `PostgresStore` long-term memory inspection.
• MCP tools for threads, checkpoints, store data, and analysis.
• MCP resources for stable readable state URIs.
• MCP prompts for repeatable debugging workflows.
• Pagination and truncation for large responses.

Installation

uv pip install "langmcp[all]"

Or run without installing:

uvx "langmcp[all]" --version

LangMCP supports Python 3.11 and 3.12. The repository includes a

`.python-version` file set to Python 3.12.

Configuration

Copy the example config and environment files:

cp examples/langmcp.example.toml langmcp.toml
cp .env.example .env

Set a read-only database URI in `.env`:

POSTGRES_URI=postgresql://READONLY_USER:READONLY_PASSWORD@HOST:5432/DB_NAME
LANGMCP_READ_ONLY=true

LangMCP loads `.env` automatically when present. Existing shell environment

variables take precedence.

Example `langmcp.toml`:

[defaults]
profile = "dev"
read_only = true
max_response_chars = 250000

[profiles.dev]
checkpointer = "${POSTGRES_URI}"
store = "${POSTGRES_URI}"
user_namespace = "users/{user_id}"

[profiles.local_sqlite]
checkpointer = "sqlite:///./.langgraph/checkpoints.db"

[profiles.local_redis]
checkpointer = "redis://localhost:6379/0"

Set `user_namespace` to the namespace template your graph uses for long-term

memory. The default is `{user_id}` for compatibility. For stores organized as

`users//...`, use `users/{user_id}`. The `summarize_user_memory` tool

also accepts `namespace_prefix` to override the profile template for one call.

Environment overrides:

• `LANGMCP_CONFIG`
• `LANGMCP_PROFILE`
• `LANGMCP_READ_ONLY`
• `POSTGRES_URI`
• `LANGMCP_CHECKPOINTER_URI`
• `LANGMCP_STORE_URI`

Verify Setup

Run:

langmcp doctor --config ./langmcp.toml

The doctor command checks connectivity, backend types, setup status, package

versions, and redacts sensitive URI fields.

Cursor Setup

See examples/cursor-mcp.json.

Minimal shape:

{
  "mcpServers": {
    "langmcp": {
      "command": "uvx",
      "args": ["langmcp[all]", "serve", "--config", "ABSOLUTE_PATH_TO_LANGMCP_TOML"],
      "env": {
        "LANGMCP_READ_ONLY": "true",
        "POSTGRES_URI": "postgresql://READONLY_USER:READONLY_PASSWORD@HOST:5432/DB_NAME"
      }
    }
  }
}

Start the server directly:

langmcp serve --config ./langmcp.toml

Example Assistant Prompts

Once connected through MCP, ask your assistant:

Use LangMCP to summarize thread THREAD_ID and check whether user memory exists for USER_ID.

Compare checkpoint CHECKPOINT_A and CHECKPOINT_B for thread THREAD_ID. Tell me what changed.

Analyze whether thread THREAD_ID is carrying too much context.

Investigate a possible memory gap for thread THREAD_ID and user USER_ID.

MCP Tools

All tools accept optional `profile` unless noted. Responses include `profile`,

`truncated`, and pagination fields where applicable.

MCP Resources

Resources expose readable state through stable MCP URIs.

For multi-part namespaces, prefer the `get_store_item` tool if your MCP client

treats `/` as a path separator inside resource parameters.

MCP Prompts

Prompts package repeatable investigations.

Backend Matrix

Security

1. Tools accept profile names, not raw DSNs.

2. `read_only=true` is enforced in v0.1.

3. Use a read-only PostgreSQL user for shared environments.

4. Passwords are redacted in `health_check` and CLI output.

5. Redis thread discovery uses `SCAN` with limits. Avoid broad scans on very large instances.

6. Commit `examples/langmcp.example.toml` and `.env.example`, not real `langmcp.toml` or `.env` files.

Development

uv pip install -e ".[all,dev]"
ruff check .
pytest tests/unit -v

Integration tests use local Docker services:

docker compose -f docker-compose.test.yml up -d
POSTGRES_URI=postgresql://langgraph:langgraph@localhost:5442/langgraph \
  REDIS_URI=redis://localhost:6379/0 \
  pytest tests/integration -v -m integration

Use the local test values from `docker-compose.test.yml`. They are for Docker

integration tests only.

Roadmap

• LangGraph Agent Server adapter.
• HTTP transport with team auth.
• Vector store inspection tools.
• Carefully scoped write workflows such as `update_thread_state` and `resume_thread`.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Good first issue ideas:

• Add examples for a specific LangGraph persistence backend.
• Improve error messages for unsupported store backends.
• Add a resource or prompt test for an edge case.

License

MIT. See LICENSE.