MCP Integration — Port Daddy

What is MCP

The Bridge Between Claude and Your Dev Environment

MCP (Model Context Protocol) is an open standard that lets AI assistants interact with external tools and data sources. Port Daddy ships a full MCP server that turns 25+ operations into tools Claude can call directly.

Native Tool Calls

Claude calls Port Daddy tools directly instead of shelling out to the CLI. Structured inputs, typed outputs, zero parsing.

Multi-Agent Ready

Every Claude session gets its own agent identity. Sessions, file claims, pub/sub, and locks all work across parallel agents.

Works Everywhere

Compatible with Claude Code, Claude Desktop, and any MCP-capable client. One server, every surface.

Installation

Two Lines to Get Started

Add Port Daddy's MCP server to your Claude configuration. The daemon starts automatically on first use.

Claude Code

Add to .claude/settings.json or project settings

// .claude/settings.json
{
  "mcpServers": {
    "port-daddy": {
      "command": "pd",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "port-daddy": {
      "command": "npx",
      "args": ["port-daddy", "mcp"]
    }
  }
}

Tools

25+ Tools at Claude's Fingertips

Every tool accepts structured JSON inputs and returns typed responses. No string parsing, no guessing.

Port Management

claim_port

Claim a stable port for a service. Accepts a semantic identity like myapp:api:main and returns a guaranteed-free port.

release_port

Release a service and free its port assignment. The port becomes available for other services immediately.

list_services

List all currently claimed services with their port assignments, timestamps, and metadata.

get_service

Get detailed information about a specific service including its port, claim time, and health status.

Sessions & Notes

start_session

Start a coordination session with a purpose description. Returns a session ID for tracking all related notes and file claims.

end_session

End an active session. Marks it as completed and releases all associated file claims.

add_note

Append an immutable note to the session log. Notes are never edited or deleted -- they form an audit trail.

list_sessions

List all sessions, optionally filtered by status (active, completed, abandoned).

list_notes

Get recent notes across all sessions or filtered to a specific session.

claim_files

Claim files for advisory conflict detection. Other agents see claimed files and can coordinate before editing.

Distributed Locks

acquire_lock

Acquire an exclusive named lock with automatic expiry. Prevents concurrent access to shared resources like databases or config files.

release_lock

Release a lock so other agents can acquire it. Only the lock owner can release.

list_locks

List all active locks with their owners, acquisition times, and TTLs.

Pub/Sub Messaging

publish_message

Publish a message to a named channel. All subscribers and pollers on that channel will receive it.

get_messages

Read messages from a channel, optionally filtered by timestamp. Supports pagination for high-volume channels.

Agent Coordination

register_agent

Register an AI agent with identity, purpose, and optional worktree ID. Returns a salvage hint if dead agents exist in the same project.

agent_heartbeat

Send a heartbeat to prove the agent is still alive. Agents that stop heartbeating are eventually marked dead.

list_agents

List all registered agents with their status (active, stale, dead), identity, and last heartbeat time.

check_salvage

Check the resurrection queue for dead agents whose work can be salvaged. Filterable by project and stack.

claim_salvage

Claim a dead agent's context to continue its work. Transfers session notes and file claims to the claiming agent.

Tunneling

start_tunnel

Start a public tunnel for a claimed service. Supports ngrok, cloudflared, and localtunnel. Returns a shareable URL.

stop_tunnel

Stop an active tunnel and tear down the connection. The local service continues running.

list_tunnels

List all active tunnels with their public URLs, providers, and associated services.

System

scan_project

Scan a directory to detect frameworks, languages, and project structure. Registers the project for orchestration.

health_check

Check the health of the daemon and all claimed services. Returns HTTP status, response times, and port availability.

daemon_status

Get daemon metrics including uptime, version, code hash, memory usage, and request counts.

activity_log

View the recent activity log with filtering by action type, service, and time range.

Resources

Live Data, Always Current

The MCP server exposes 5 read-only resources that Claude can inspect at any time. These reflect the live state of your development environment.

port-daddy://services

All claimed services with port assignments, metadata, and health status.

port-daddy://sessions

Active coordination sessions with their notes, file claims, and participants.

port-daddy://agents

Registered AI agents with identity, status, heartbeat times, and purposes.

port-daddy://locks

Active distributed locks with owners, TTLs, and acquisition timestamps.

port-daddy://tunnels

Active tunnels with public URLs, providers, and linked service details.

Claude Meets Port Daddy