Run your first protected MCP workflow

A complete local evaluation with a safe MCP fixture, email verification, real decisions and audit export. No production credentials required.

1. Prerequisites and workspace

Use a disposable MCP server and synthetic data. You need an account, permission to manage agents, servers and policies, and an agent that can reach an HTTP MCP endpoint or launch the Local Connector. Client compatibility is tracked in Integrations.

Register with your organization name, verify your email, then sign in. Registration creates your tenant workspace; there is no separate workspace-creation CLI. For a local evaluation, run the repository's Docker Compose stack:

# From the repository root, with Docker and Node.js installed:
docker compose -f tests/evaluation-compose.yml up -d --build
node scripts/evaluation-e2e.mjs
# Dashboard: http://127.0.0.1:18080
# Concrete client config: .artifacts/evaluation/mcp.json
# Disposable login: .artifacts/evaluation/browser-account.json
# Test summary: .artifacts/evaluation/result.json

The script creates and verifies a disposable account using local mail capture, registers the supplied fixture, exercises allow/deny/approval and replay protection, and exports evidence. The fixture only returns synthetic text. Keep generated credential files local. Use the dashboard login in browser-account.json to inspect this workspace.

2. Register one identity per agent

Open Agents → Create agent, choose development, and copy the one-time API key into your local credential store. Repeat with a distinct identity for Claude Code, Cursor, Codex or an internal agent. Never commit keys. The examples below use replacement values, not real credentials.

curl "$API/api/v1/agents" -H "Authorization: Bearer $ACCESS_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"claude-code-evaluation","environment":"development","trust_level":"unverified"}'
# Repeat with cursor-evaluation, codex-evaluation or internal-evaluation.
# API=http://localhost:8090; ACCESS_TOKEN is your management session token.
# Response data.api_key is issued once; it is not ACCESS_TOKEN.

3. Connect a remote MCP server

In MCP Servers, register your reachable test upstream URL, select HTTP / Streamable HTTP, scan its tools, then verify the server only after reviewing it. Copy its server ID. The agent must connect to the gateway URL below, rather than the upstream. The local evaluation generates a concrete mcp.json containing the server URL and a disposable agent credential. Copy it into your client configuration; never commit it.

Claude Code — project .mcp.json

{
  "mcpServers": {
    "agentgate": {
      "type": "http",
      "url": "https://gateway.agentgatelabs.com/gateway/mcp/SERVER_ID",
      "headers": {
        "Authorization": "Bearer AGENT_KEY"
      }
    }
  }
}

Cursor — project .cursor/mcp.json

{
  "mcpServers": {
    "agentgate": {
      "type": "http",
      "url": "https://gateway.agentgatelabs.com/gateway/mcp/SERVER_ID",
      "headers": {
        "Authorization": "Bearer AGENT_KEY"
      }
    }
  }
}

Codex — ~/.codex/config.toml

[mcp_servers.agentgate]
url = "https://gateway.agentgatelabs.com/gateway/mcp/SERVER_ID"
bearer_token_env_var = "AGENTGATE_AGENT_KEY"

Internal agent — HTTP JSON-RPC

curl "$GATEWAY/gateway/mcp/$SERVER_ID"   -H "Authorization: Bearer $AGENTGATE_AGENT_KEY"   -H 'Content-Type: application/json'   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# GATEWAY=http://localhost:8091 for Compose.

These are configuration examples, not certification of every client release. Confirm initialization and tools/list with your installed version before enabling calls.

Client configuration references: Claude Code MCP documentation, Cursor MCP documentation, Codex MCP documentation.

4. Local tools: build and configure Local Connector

With Go 1.24+ installed, build the actual repository binary and add it to PATH. Register a server with Local connector transport, then use this client JSON config. Choose an already-installed MCP server binary and a disposable directory.

go build -o agentgate-local-connector ./apps/local-connector

{
  "mcpServers": {
    "agentgate-local": {
      "command": "agentgate-local-connector",
      "env": {
        "AGENTGATE_GATEWAY_URL": "http://localhost:8091",
        "AGENTGATE_SERVER_ID": "SERVER_ID",
        "AGENTGATE_AGENT_KEY": "AGENT_KEY",
        "AGENTGATE_UPSTREAM_COMMAND": "YOUR_INSTALLED_MCP_BINARY",
        "AGENTGATE_UPSTREAM_ARGS": "[\"/absolute/test/project\"]"
      }
    }
  }
}

On Windows, build agentgate-local-connector.exe. Current stdio upstream execution is per request; long-lived process supervision and automatic binary packaging are not available. Test your server's session requirements.

5. Create an executable policy

Rules support exact tool names or a trailing wildcard, optional environment and capability, and allow, deny or approval_required actions. Lower priority numbers run first; the first matching custom rule wins. Built-in secret, production-destructive and egress denials take precedence.

{
  "kind": "custom",
  "rules": [
    {
      "tool": "filesystem.write",
      "environment": "development",
      "action": "approval_required"
    }
  ]
}

Create this rule in the dashboard to require approval for development file writes. Production database writes remain denied. Production database reads require approval by default. Invalid or unsupported rules are rejected when saved.

6. Simulate before execution

Open Policies → Simulator and submit this policy input, or call the management endpoint. With default packs enabled, expect APPROVAL_REQUIRED. Change capabilities to database_write to verify DENY; simulate shell.exec in production for DENY and github.read_file in development for ALLOW.

{
  "tool_name": "database.query",
  "environment": "production",
  "server_verified": true,
  "capabilities": [
    "database_read"
  ],
  "arguments": {
    "query": "select 1"
  }
}

curl "$API/api/v1/policies/simulate" -H "Authorization: Bearer $ACCESS_TOKEN"   -H 'Content-Type: application/json' --data-binary @simulation.json

7. Send a call and inspect the decision

Use the exact tool name and arguments discovered on your test server. This sample assumes it exposes database.query; otherwise replace that name. Never attach a production database to this walkthrough.

curl "$GATEWAY/gateway/mcp/$SERVER_ID/tools/call"   -H "Authorization: Bearer $AGENTGATE_AGENT_KEY" -H 'Content-Type: application/json'   -d '{"name":"database.query","arguments":{"query":"select 1","environment":"production"}}'

HTTP 422 with APPROVAL_REQUIRED means execution is waiting; HTTP 403 means denied. In Approvals, approve or deny the exact request. Approval returns a one-time token: retry unchanged arguments with approval_token at the top level. Expired or replayed tokens do not authorize execution. Open Audit Events to inspect agent, tool, decision, risk and matched rules. Your overview highlights “First protected call!” when a real allow/deny/approval decision is available.

8. Export the evidence

In Audit Events, export CSV or NDJSON using an account with audit.export permission. NDJSON contains one JSON object per line.

curl "$API/api/v1/audit-events/export?format=csv"   -H "Authorization: Bearer $ACCESS_TOKEN" -o audit.csv
curl "$API/api/v1/audit-events/export?format=ndjson"   -H "Authorization: Bearer $ACCESS_TOKEN" -o audit.ndjson

Repository verification: scripts/evaluation-e2e.mjs exercises registration, discovery, allow, deny, approval and replay prevention against a configured fixture. Authorization records are immutable within retention. Execution outcomes are appended separately; unresolved outcomes are held for investigation.