Skip to main content

Claude Code Setup

Integrate ACE with Claude Code for AI-assisted development with self-improving playbooks.

Prerequisites​

  • Claude Code installed
  • ACE account with verified email
  • API key with appropriate scopes

Configuration​

Step 1: Create an API Key​

  1. Go to app.aceagent.io
  2. Navigate to API Keys
  3. Create a key with all scopes enabled:
    • playbooks:read - List and read playbooks
    • playbooks:write - Create playbooks and versions
    • outcomes:write - Record task outcomes
    • evolution:write - Trigger evolution
    • evolution:read - Check evolution status

Step 2: Add the MCP Server​

The fastest way to add ACE is with the claude mcp add command:

claude mcp add --transport sse ace https://aceagent.io/mcp/sse \
  --header "X-API-Key: YOUR_API_KEY"

This adds the server to your local scope (current project only) by default.

To make it available across all projects, use --scope user:

claude mcp add --transport sse --scope user ace https://aceagent.io/mcp/sse \
  --header "X-API-Key: YOUR_API_KEY"

To share it with your team, use --scope project (adds to .mcp.json in your project root):

claude mcp add --transport sse --scope project ace https://aceagent.io/mcp/sse \
  --header "X-API-Key: YOUR_API_KEY"

Step 3: Verify Setup​

Start Claude Code and check the MCP server is connected:

> /mcp

This shows all connected MCP servers and their status. Then test it:

> "List my ACE playbooks"

Using ACE with Claude Code​

Development Workflows​

Code Review:

You: "Get my code-review playbook and review the changes in this PR"
Claude: [Fetches playbook, reviews code following guidelines]

Documentation:

You: "Using my documentation playbook, document the API in src/api/"
Claude: [Follows playbook instructions to create docs]

Recording Outcomes​

After Claude completes a task:

You: "Record an outcome for the code-review playbook:
- Task: Reviewed authentication module PR
- Outcome: success
- Notes: Caught SQL injection vulnerability in user lookup"

Triggering Evolution​

When you want to improve a playbook:

You: "Trigger evolution for my code-review playbook"
Claude: [Triggers evolution job]

You: "Check the evolution status for job xyz-123"
Claude: [Reports evolution progress/completion]

Project-Specific Playbooks​

Store playbook IDs in your project's CLAUDE.md for quick reference:

## ACE Playbooks

| Task | Playbook ID | When to Use |
|------|-------------|-------------|
| Code reviews | `abc-123-def` | All PR reviews |
| Documentation | `ghi-456-jkl` | API and README updates |

Then reference them in conversations:

"Using playbook abc-123-def, review the changes in src/"

Using Environment Variables​

Keep API keys out of shared config files using environment variable expansion in .mcp.json:

{
  "mcpServers": {
    "ace": {
      "type": "sse",
      "url": "https://aceagent.io/mcp/sse",
      "headers": {
        "X-API-Key": "${ACE_API_KEY}"
      }
    }
  }
}

Set in your shell profile:

export ACE_API_KEY="ace_..."

Troubleshooting​

MCP Server Not Loading​

  1. Check server status with /mcp inside Claude Code
  2. Verify the server was added: 
    claude mcp list
  3. Verify the URL is correct: https://aceagent.io/mcp/sse
  4. Try removing and re-adding: 
    claude mcp remove ace
    claude mcp add --transport sse ace https://aceagent.io/mcp/sse \
      --header "X-API-Key: YOUR_API_KEY"

Authentication Errors​

  • Verify API key is correct in dashboard
  • Check key has required scopes
  • Try regenerating the key

Slow Tool Responses​

  • First MCP call establishes the connection (slower)
  • Subsequent calls should be faster
  • Check your network connection to the MCP server

Tools Not Found​

  • Run /mcp to check server status
  • Verify API key scopes include tool access
  • Try restarting Claude Code

Next Steps​