MCP Server

The @defiant/mcp package exposes Defiant’s core capabilities as MCP (Model Context Protocol) tools. This lets Claude call Defiant directly — create sprints, check status, resolve inbox items — without leaving the conversation.

What MCP enables

Instead of switching to the CLI or a browser, you can talk to Claude and say: “Create a sprint to add a dark mode toggle to my B2B SaaS project.” Claude calls the defiant_sprint_create MCP tool and shows you the result inline.

Installation

npm install -g @defiant/mcp
# or
pnpm add -g @defiant/mcp

Connecting to Claude

Add to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "defiant": {
      "command": "defiant-mcp",
      "env": {
        "SUPABASE_URL": "https://xxx.supabase.co",
        "SUPABASE_ANON_KEY": "eyJ...",
        "DEFIANT_JWT": "eyJ..."
      }
    }
  }
}

The MCP server is pre-configured in Claude Code when the @defiant/mcp package is installed globally. Verify:

claude mcp list
# defiant — @defiant/mcp (connected)

Start the MCP server manually and connect via stdio:

SUPABASE_URL=... SUPABASE_ANON_KEY=... DEFIANT_JWT=... defiant-mcp

Available tools

The MCP server exposes five tools:

`defiant_sprint_create`

Create a new sprint.

Parameters:

Parameter	Type	Required	Description
`project_id`	string	yes	Project ID
`goal`	string	yes	Sprint goal in plain language
`priority`	string	no	`low`, `normal`, `high`

Example Claude prompt:

Create a sprint to add email notification preferences to the settings page. Users should be able to toggle marketing, product, and security emails. Project ID is proj_01hw…

Claude calls defiant_sprint_create with:

{
  "project_id": "proj_01hw...",
  "goal": "Add email notification preferences to the settings page. Users can toggle: marketing emails, product updates, security alerts. Preferences persist to the database.",
  "priority": "normal"
}

Response shown to Claude:

{
  "sprint_id": "spr_01hwxyz...",
  "state": "INTAKE",
  "message": "Sprint created. Captain agent dispatched."
}

`defiant_sprint_status`

Get the current status of a sprint.

Parameters:

Parameter	Type	Required	Description
`sprint_id`	string	yes	Sprint ID

Example Claude prompt:

What’s the status of sprint spr_01hwxyz…?

Response:

{
  "sprint_id": "spr_01hwxyz...",
  "state": "BUILD",
  "goal": "Add email notification preferences...",
  "active_agents": ["builder"],
  "prs_open": 1,
  "tokens_used": 47823,
  "tokens_remaining": 152177,
  "elapsed": "00:08:14"
}

`defiant_inbox_list`

List pending inbox items that need human attention.

Parameters:

Parameter	Type	Required	Description
`priority`	string	no	Filter by priority: `critical`, `high`, `low`
`project_id`	string	no	Filter by project

Example Claude prompt:

Do I have any critical items in my Defiant inbox?

Response:

{
  "items": [
    {
      "id": "inbox_01hw...",
      "priority": "critical",
      "title": "Sprint spr_01hw... BLOCKED — PR #44 failing CI",
      "description": "Test coverage is 71%, below the 80% minimum (mandate_14). Builder could not resolve within token budget.",
      "sprint_id": "spr_01hw...",
      "created_at": "2026-05-05T14:22:00Z"
    }
  ]
}

`defiant_inbox_resolve`

Resolve a pending inbox item with a human decision.

Parameters:

Parameter	Type	Required	Description
`inbox_id`	string	yes	Inbox item ID
`response`	string	yes	Your resolution or decision

Example Claude prompt:

Resolve inbox item inbox_01hw… — tell it to lower the coverage threshold for this sprint to 70%.

Claude calls defiant_inbox_resolve:

{
  "inbox_id": "inbox_01hw...",
  "response": "Lower the test coverage threshold to 70% for this sprint only. Add a tech debt note in the PR."
}

The Conductor receives the resolution and retries the sprint from the last checkpoint.

`defiant_projects_list`

List all projects.

Parameters: None.

Example Claude prompt:

List my Defiant projects.

Response:

{
  "projects": [
    {
      "id": "proj_01hw...",
      "name": "my-app",
      "repo": "yourorg/my-app",
      "vertical": "b2b-saas",
      "active_sprints": 1
    }
  ]
}

Example conversation

Here’s what a full interaction looks like with Defiant connected to Claude:

User: Create a sprint to add a Stripe billing portal to my SaaS app.
      Project is proj_01hw...

Claude: I'll create that sprint now.
[calls defiant_sprint_create]

Sprint created: spr_01hw...
State: INTAKE — Captain agent is reviewing the goal.

The Captain will check your token budget and select the right agents.
For a Stripe billing portal, expect the Ambassador agent to handle the
Stripe integration and the Counselor to check compliance. I'll check
back on the status.

---

User: What's the status?

Claude: [calls defiant_sprint_status]

Sprint spr_01hw... is in BUILD state.
- Builder is implementing the billing portal component (task 1 of 3)
- Builder is implementing the Stripe webhook handler (task 2 of 3)
- Task 3 (Stripe Connect setup) hasn't started yet
- 2 PRs open: #47, #48
- 62,401 tokens used / 200,000 budget
- Elapsed: 18 minutes

---

User: Do I have any inbox items?

Claude: [calls defiant_inbox_list]

You have 1 inbox item:
- MEDIUM: Sprint spr_01hw... — Counselor flagged that your Stripe webhook
  handler does not verify the Stripe-Signature header.
  This is required by Stripe's ToS and mandate_45.
  The Builder is waiting for direction.

Do you want me to resolve this with an instruction to add HMAC verification?

User: Yes, resolve it.

Claude: [calls defiant_inbox_resolve]
Resolved. Instructed the Builder to add Stripe webhook signature
verification using the stripe.webhooks.constructEvent() method.
The sprint will continue from where it paused.

Security note

The MCP server has the same access level as your Supabase JWT. For production use, create a scoped service account rather than using your personal admin JWT. MCP tool calls are logged in the Defiant event log.