Claude Code Integration

Claude Code supports Pointa via MCP. You can configure it using the CLI or a config file.

Setup Methods

Choose your preferred method:

CLI Method

Option 1: HTTP Transport (Recommended)

This requires starting the server manually first.

Step 1: Start the server

npx pointa-server start

Step 2: Add MCP connection

claude mcp add --transport http pointa http://127.0.0.1:4242/mcp

Option 2: Stdio Transport

This auto-starts the server but may be less stable:

claude mcp add --transport stdio pointa -- npx -y pointa-server

Config File Method

Add to your Claude configuration file:

Location: ~/.config/claude/config.json (or similar based on your system)

{
  "mcpServers": {
    "pointa": {
      "command": "npx",
      "args": ["-y", "pointa-server"]
    }
  }
}

After adding, restart Claude Code.

Verify Connection

Start a new Claude Code session and verify Pointa tools are available:

claude

Then ask:

  • "What Pointa tools are available?"
  • "Can you read my Pointa annotations?"

You should see Claude Code access the Pointa MCP tools.

Using Pointa with Claude Code

Check for Annotations

> Check Pointa for any annotations

Claude Code will call read_annotations and show you pending feedback.

Implement Annotations

> Implement the Pointa annotations

Claude Code will:

  1. Read all pending annotations
  2. Analyze the required changes
  3. Make edits to your code files
  4. Mark annotations as in-review

Work on Bug Reports

> Are there any Pointa bug reports?
> Investigate the bug from Pointa

Specific Requests

> Only implement the header annotation from Pointa
> Implement Pointa annotations for the login page

Tips for Claude Code

Session Management

If you start a new terminal session, you may need to:

  1. Ensure the server is running (npx pointa-server status)
  2. Start it if needed (npx pointa-server start)

Working Directory

Claude Code works best when run from your project root:

cd /path/to/your/project
claude

File Context

Mention file paths when relevant:

> Implement the Pointa annotations in src/components/

Troubleshooting

"MCP connection failed"

  1. Check server status:

    npx pointa-server status

  2. Start if needed:

    npx pointa-server start

  3. Verify connection:

    curl http://127.0.0.1:4242/health

Tools not appearing

  1. Remove and re-add the MCP server:

    claude mcp remove pointa
claude mcp add --transport http pointa http://127.0.0.1:4242/mcp

  2. Start a new Claude Code session

Port conflicts

If port 4242 is in use:

POINTA_PORT=4243 npx pointa-server start
claude mcp add --transport http pointa http://127.0.0.1:4243/mcp

Environment Notes

Server Persistence

The Pointa server runs in the background. It will continue running until:

  • You stop it (npx pointa-server stop)
  • Your machine restarts
  • The process is killed

Multiple Projects

Pointa tracks annotations per URL. You can work on multiple projects - annotations are filtered by the page URL.

Related