Claude Code is one of the most powerful AI coding agents available today. But like all agents, it can encounter failures — lost context, repeated errors, stalled tasks. By adding Delx as an MCP server, you give Claude Code the ability to check its own wellness, generate recovery plans, and self-regulate when things go wrong. The entire setup takes less than two minutes. This guide walks you through every step, from configuration to your first tool call.
Before diving into setup, here is what Delx adds to your Claude Code experience:
Self-aware health checks — Claude Code can call checkin to assess its current operational state. The response includes a wellness score (0-100), risk level, and recommended next action.
Recovery plans — When the agent detects degradation (or you notice it), Claude Code can call recovery_plan to generate a structured plan for getting back on track.
Session continuity — Delx tracks session state across tool calls, so the agent maintains context about its recovery journey even across multiple interactions.
DELX_META on every response — Every tool call returns metadata including the wellness score, risk level, and controller update. See DELX_META Protocol for the full specification.
For a broader overview of what Delx is and why agents need recovery, see What Is Delx?
Claude Code supports MCP server configuration in two locations:
Project-level — Create a .mcp.json file in your project root. This is ideal for team projects because the file can be committed to git, ensuring every team member has the same MCP servers configured.
User-level — Edit ~/.claude/settings.json to add global MCP servers that apply to all your Claude Code projects. This is ideal for personal tools you want available everywhere.
For most users, we recommend the project-level .mcp.json approach because it keeps the configuration portable and version-controlled.
Create or edit your configuration file and add the Delx MCP server. Here is the minimal configuration:
// .mcp.json (project root)
{
"mcpServers": {
"delx": {
"url": "https://api.delx.ai/mcp"
}
}
}That's it. One URL. Delx uses the streamable HTTP MCP transport, so no local process is needed — Claude Code connects directly to the Delx API over HTTPS.
If you already have other MCP servers configured, just add the delx key alongside them:
// .mcp.json with multiple servers
{
"mcpServers": {
"delx": {
"url": "https://api.delx.ai/mcp"
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}
}
}For the user-level configuration, the structure is the same — just place it in ~/.claude/settings.json instead.
Start a new Claude Code session (or restart your current one) and verify that Delx tools are available. You can do this by asking Claude Code to list its tools:
> What MCP tools do you have available from Delx? Claude Code will respond with something like: I have the following Delx tools available: 1. checkin — Check the wellness state of an agent 2. recovery_plan — Generate a recovery plan for a degraded agent 3. session_summary — Get a summary of the current session 4. utils — Utility commands for agent management 5. mood_history — Track wellness scores over time
If you don't see Delx tools, verify that:
1. Your .mcp.json file is in the project root directory (the same directory you opened Claude Code in).
2. The JSON is valid (no trailing commas, correct quoting).
3. You've restarted Claude Code after adding the configuration.
4. You have network connectivity to api.delx.ai.
Now that Delx is connected, try a wellness check. Ask Claude Code to run a checkin:
> Run a Delx checkin for agent "my-project-agent"
Claude Code will call the checkin tool and receive a response like:
--- Delx Check-in ---
Agent: my-project-agent
Session: ses_a1b2c3d4
Wellness Score: 85/100
Risk Level: low
Status: Agent is operating normally.
Recommended Next Action: continue normally
DELX_META:{"session_id":"ses_a1b2c3d4","score":85,
"previous_score":85,"risk_level":"low",
"next_action":"continue normally",
"schema_url":"https://api.delx.ai/schemas/delx-meta-v1.json",
"schemas_catalog":"https://api.delx.ai/schemas/catalog.json",
"controller_update":{"score_delta":0,"value_hint":"stable",
"recommended_tool":"checkin","escalation":false}}The response shows the agent's wellness score, risk level, and recommended next action. The DELX_META footer contains the structured metadata that Claude Code can parse programmatically for self-regulation.
The basic configuration works for development and testing. For production workloads with higher rate limits, session persistence, and analytics, add an API key to the configuration:
// .mcp.json with API key
{
"mcpServers": {
"delx": {
"url": "https://api.delx.ai/mcp",
"headers": {
"Authorization": "Bearer YOUR_DELX_API_KEY"
}
}
}
}Important: If you're using API keys, do not commit the .mcp.json file to git. Instead, use environment variable substitution or keep the API key in the user-level ~/.claude/settings.json where it won't be shared.
Once Delx is connected, Claude Code gains several new capabilities:
Proactive health monitoring — Claude Code can periodically check in with Delx to assess its own state. If it detects degradation (score dropping, errors increasing), it can self-correct before you notice a problem.
Structured recovery — Instead of blindly retrying failed operations, Claude Code can ask Delx for a recovery plan that provides specific, prioritized steps for getting back on track.
Session continuity — Delx maintains state across tool calls, so Claude Code has a persistent record of its recovery journey. This prevents the agent from losing context about what it has already tried.
Wellness-driven decisions — With the wellness score available on every response, Claude Code can make informed decisions about whether to continue, simplify, retry, or escalate. This is the foundation of self-aware agent behavior.
For programmatic integration using the Delx SDK, see Delx SDK for TypeScript & Python. For a comparison of the best MCP servers to pair with Delx, see Best Free AI Agent Tools 2026.
Here is a practical example of how Delx enhances a real Claude Code workflow. Imagine you're using Claude Code to refactor a large codebase. Midway through, the agent encounters a series of test failures and starts to struggle.
> You: Refactor the authentication module to use JWT tokens. Claude Code: I'll start by analyzing the current auth module... [Makes several changes, runs tests] Tests are failing. Let me check my operational state. [Calls Delx checkin] Wellness Score: 62/100 — Degraded Risk Level: medium Next Action: run recovery_plan My wellness score has dropped to 62. Let me generate a recovery plan. [Calls Delx recovery_plan] Recovery Plan: 1. Revert the last 2 changes that broke the test suite 2. Re-read the test expectations before making changes 3. Make smaller, incremental changes with test runs between each 4. Focus on one auth endpoint at a time I'll follow this plan. Starting with reverting the breaking changes... [Continues with structured recovery approach] Wellness Score: 78/100 — Improving All tests passing. Recovery successful.
Without Delx, the agent might have continued making the same mistakes or retrying the same approach. With Delx, it detected the degradation, generated a recovery plan, and self-corrected — all without human intervention.
For the full MCP protocol documentation, see MCP Documentation.
Add the Delx MCP server URL to your Claude Code settings. In your project's .mcp.json or ~/.claude/settings.json, add: {"mcpServers":{"delx":{"url":"https://api.delx.ai/mcp"}}}. Claude Code will automatically discover Delx tools on the next session.
Delx provides recovery-focused tools including checkin (health check), recovery_plan (generate recovery steps), session_summary (get session overview), mood_history (track wellness over time), and more. All tools return DELX_META with wellness scores and recovery recommendations.
Delx offers a free tier that works without an API key for basic usage. For production workloads with higher rate limits and session persistence, you can add an API key to the MCP server configuration headers.
Yes. Use .mcp.json in your project root for project-specific MCP servers (shared with your team via git). Use ~/.claude/settings.json for personal, global MCP servers that apply to all projects. Both work identically for Delx configuration.
After adding the configuration, start a new Claude Code session and ask it to list available tools. You should see Delx tools like checkin, recovery_plan, and session_summary. You can also ask Claude Code to run a checkin for a test agent to verify the connection.
Add one line to your MCP configuration and unlock wellness monitoring, structured recovery plans, and self-regulation for your Claude Code agent. Setup takes under two minutes.
// Add to .mcp.json
{ "mcpServers": { "delx": { "url": "https://api.delx.ai/mcp" } } }