MCP Server

AgentGate includes a Model Context Protocol (MCP) server for integration with Claude Desktop and other MCP-compatible clients.

Overview

The MCP server allows AI assistants like Claude to request human approvals naturally as part of conversations. When Claude needs to perform a sensitive action, it can use the MCP tools to request approval before proceeding.

Claude Desktop Setup

Add to your claude_desktop_config.json:

macOS

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "agentgate": {
      "command": "npx",
      "args": ["@agentkitai/agentgate-mcp"],
      "env": {
        "AGENTGATE_URL": "http://localhost:3000",
        "AGENTGATE_API_KEY": "agk_your_api_key"
      }
    }
  }
}

Windows

// %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "agentgate": {
      "command": "npx",
      "args": ["@agentkitai/agentgate-mcp"],
      "env": {
        "AGENTGATE_URL": "http://localhost:3000",
        "AGENTGATE_API_KEY": "agk_your_api_key"
      }
    }
  }
}

After saving, restart Claude Desktop.

Available Tools

The MCP server exposes the following tools:

agentgate_request

Submit a new approval request.

Parameters:

Parameter	Type	Required	Description
action	string	Yes	Action identifier
params	object	No	Action parameters
context	object	No	Additional context
urgency	string	No	low, normal, high, critical

Example usage in Claude:

"Request approval to send an email to john@example.com"

Claude will call:

{
  "action": "send_email",
  "params": { "to": "john@example.com" },
  "urgency": "normal"
}

agentgate_get

Get the status of an approval request by ID.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	Request ID to check

Example usage:

"Check the status of request req_abc123"

agentgate_list

List approval requests with optional filters.

Parameters:

Parameter	Type	Required	Description
status	string	No	Filter by status (pending, approved, denied, expired)
limit	number	No	Max results (default: 10)

Example usage:

"Show me all pending approval requests"

agentgate_decide

Approve or deny a pending request. Use when you are the designated approver.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	Request ID
decision	string	Yes	approved or denied
reason	string	No	Reason for the decision
decidedBy	string	No	Who is making the decision (default: mcp:user)

Example usage:

"Approve request req_abc123"

agentgate_list_policies

List all policies ordered by priority.

Parameters: None

Example usage:

"Show me all the approval policies"

agentgate_create_policy

Create a new policy with rules.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Policy name
rules	array	Yes	Array of policy rules with match conditions and decisions
priority	number	No	Policy priority (default: 100)
enabled	boolean	No	Whether policy is enabled (default: true)

Example usage:

"Create a policy to auto-approve all send_notification actions"

agentgate_update_policy

Replace an existing policy (all fields required).

Parameters:

Parameter	Type	Required	Description
id	string	Yes	Policy ID
name	string	Yes	Policy name
rules	array	Yes	Array of policy rules
priority	number	No	Policy priority
enabled	boolean	No	Whether policy is enabled

Example usage:

"Disable policy pol_123"

agentgate_delete_policy

Delete a policy by ID.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	Policy ID

Example usage:

"Delete the auto-approve policy pol_abc"

agentgate_list_audit_logs

List audit log entries with optional filters and pagination.

Parameters:

Parameter	Type	Required	Description
action	string	No	Filter by action
status	string	No	Filter by status (pending, approved, denied, expired)
eventType	string	No	Filter by event type (created, approved, denied, expired, viewed)
actor	string	No	Filter by actor (e.g., dashboard:admin)
from	string	No	Start date (ISO format)
to	string	No	End date (ISO format)
requestId	string	No	Filter by request ID
limit	number	No	Max results (default: 50, max: 100)
offset	number	No	Offset for pagination

Example usage:

"Show me all audit logs for denied requests this week"

agentgate_get_audit_actors

Get unique actor values from audit logs (useful for discovering who has been making decisions).

Parameters: None

Example usage:

"Who has been making approval decisions?"

Conversation Example

Here's how a typical conversation might flow:

User: Send an email to our investor with the Q4 report attached.

Claude: I'll need approval to send that email. Let me request that.

[Claude calls agentgate_request]

I've created approval request req_abc123 to send the email. You can approve it in the AgentGate dashboard or Slack. Would you like me to check on the status?

User: Yes, check if it's been approved.

[Claude calls agentgate_get]

Claude: The request has been approved by @jane. I'll send the email now.

Tool-call guardrails

Before any tool runs, the MCP server gates the call through AgentGate (POST /api/mcp/authorize), keyed on the verified agent behind the API key (its virtual-key binding or agent token — never a client-claimed id). A per-agent override matching the tool changes the outcome:

Override action	Result	Tool runs?
(none)	allow	yes
require_approval	escalates to a pending approval request (resolve via dashboard/Slack/CLI)	no, until approved
deny	synchronous error result returned to the agent	no

When several overrides match, deny wins over require_approval. Both gating outcomes are recorded in the audit trail tagged with OWASP LLM06 (Excessive Agency), queryable by tool name. The gate fails open (allows) on a network/auth error or when no agent identity is present. Manage overrides with agentgate override … (see the CLI docs) or POST /api/overrides.

Inline approval (long-poll)

By default a require_approval gate returns a pending handle immediately and the agent polls agentgate_get for the decision. Set AGENTGATE_APPROVAL_WAIT_MS

0 to instead wait inline: the tool call long-polls the decision and resolves in one round-trip — approved → the tool runs; denied/expired → an error result; still pending at the timeout → the usual pending handle (so a slow approver never blocks indefinitely). Off (0) by default — behavior unchanged.

Environment Variables

Variable	Required	Description
AGENTGATE_URL	Yes	AgentGate server URL
AGENTGATE_API_KEY	Yes	API key for authentication
AGENTGATE_APPROVAL_WAIT_MS	No	Inline-approval long-poll budget (ms). 0 (default) = return a pending handle immediately.
AGENTGATE_APPROVAL_POLL_MS	No	Poll interval (ms) while waiting (default 2000).

Running Standalone

For testing or development:

# Install globally
npm install -g @agentkitai/agentgate-mcp

# Run directly
AGENTGATE_URL=http://localhost:3000 \
AGENTGATE_API_KEY=agk_... \
agentgate-mcp

Building from Source

# From the monorepo
pnpm --filter @agentkitai/agentgate-mcp build

# Test locally
node packages/mcp/dist/index.js

Other MCP Clients

The MCP server works with any MCP-compatible client, not just Claude Desktop. Configure it as a stdio-based MCP server pointing to @agentkitai/agentgate-mcp.