MCP Setup Guide

The MCP (Model Context Protocol) Gateway governs the tool calls your coding agents make. Cursor, Windsurf and Claude Code are MCP clients — you register the target MCP server they call (a database, filesystem or GitHub MCP server) and route the client through Palveron for policy checks, PII detection and audit logging.

How It Works

1. You register the target MCP server with Palveron — from the catalog or by custom address
2. Palveron scans it and an Admin activates it (only an ACTIVE server is served)
3. Your coding agent talks to Palveron's per-server proxy endpoint instead of the MCP server directly
4. Guardrails check the tool name, parameters and context against your policies
5. If approved, the call is forwarded to the actual MCP server and logged as a trace

Step 1 — Register the target MCP server

Palveron can proxy requests to any reachable MCP server. Registering and scanning is an Editor action.

Dashboard

1. Navigate to Integrations → MCP (/integration/mcp)
2. Click Add server and either pick a server from the catalog (searchable official MCP registry, one-click connect) or enter a custom address
3. Enter the server URL and authentication details

Registration does not auto-scan; run a scan as a separate step (see Step 1b).

API

curl -X POST https://gateway.palveron.com/api/v1/mcp/servers \
  -H "Authorization: Bearer pv_live_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub MCP",
    "server_url": "https://api.githubcopilot.com/mcp/"
  }'

Required fields: name, server_url (a Streamable-HTTP MCP endpoint). Optional: description, connector_type (free-form label, defaults to custom), auth_method, auth_config (free-form JSON), is_proxied. The response contains the server id — you need it for the proxy URL below. New servers start in PENDING_APPROVAL.

Step 1b — Scan the server

curl -X POST https://gateway.palveron.com/api/v1/mcp/servers/{id}/scan \
  -H "Authorization: Bearer pv_live_your_project_key"

The scan discovers the server's tools, classifies each one's risk, and seeds a starting verdict per tool (see Tool Policies). If the target is unreachable the scan is honest: it returns 200 { "scanned": false, "reason": "unreachable", "target": "…" } — not a server error.

Step 1c — Activation (Admin)

A newly registered server is PENDING_APPROVAL and serves nothing — the proxy denies every call to a non-ACTIVE server (a PENDING_APPROVAL server returns JSON-RPC -32002). After reviewing the discovered tools, an Admin activates the server (Integrations → MCP → Approve). Activation, pausing and rejection are dedicated, audited Admin actions. This role split — Editor connects and scans, Admin activates — keeps a human in the loop before any traffic flows.

Step 2 — Point your coding agent at the proxy

The governed endpoint is the per-server JSON-RPC proxy:

https://gateway.palveron.com/api/v1/mcp/proxy/{server_id}

It accepts any JSON-RPC 2.0 request (initialize and tools/list pass through; tools/call is policy-checked). Optionally send an X-Agent-Id header with a registered agent id so calls are attributed to that agent — an unknown id is treated as anonymous.

Cursor

Open Cursor Settings → MCP Servers → Add Server (type: HTTP, Bearer = your project API key):

{
  "mcpServers": {
    "palveron-governed-github": {
      "url": "https://gateway.palveron.com/api/v1/mcp/proxy/{server_id}",
      "headers": {
        "Authorization": "Bearer pv_live_your_project_key",
        "X-Agent-Id": "ckagent..."
      }
    }
  }
}

Windsurf

Windsurf uses the same MCP configuration format — add the same entry under Windsurf Settings → MCP.

Claude Code

For Claude Code (Anthropic's CLI agent), add the same MCP server entry to your configuration.

For self-hosted deployments, replace the host with your gateway (e.g. http://localhost:8080/api/v1/mcp/proxy/{server_id}).

Step 3 — Tool Policies

The scan seeds a starting verdict for every tool, but you can add your own. Bind a policy to a scanned tool via mcp_tool_id from GET /api/v1/mcp/servers/{id}/tools:

curl -X POST https://gateway.palveron.com/api/v1/mcp/policies \
  -H "Authorization: Bearer pv_live_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_tool_id": "clxyz...",
    "action": "REQUIRE_APPROVAL",
    "reason": "Destructive database operations require human approval"
  }'

Any other action value returns 400 listing the allowed set. Creating a policy is an Editor action; deleting one is an Admin action. See the MCP API reference for the full body.

Approval Queue

When a tool call triggers a REQUIRE_APPROVAL policy, it is placed in the queue:

1. The coding agent's call is paused (JSON-RPC -32004, with the request id)
2. An approver reviews the request under Integrations → MCP
3. On approval, the call is forwarded once — the grant is one-shot and bound to the exact arguments it was requested for (different arguments open a new approval request); on rejection, an error is returned

Tool governance & drift detection

When an Admin activates (or re-activates) a server, Palveron freezes a per-tool fingerprint over each tool's name, description and input parameters — the approved state. On every later call the current tool surface is compared against that anchor:

• Unchanged → the call proceeds under its policy.
• Drifted (a tool changed after approval — a classic rug-pull / tool-poisoning vector) → the call is blocked (-32002, APPROVED_FINGERPRINT_MISMATCH) and audited (McpToolDrift → OCSF/SIEM) until an Admin reviews and re-approves the server. The cockpit reports "unchanged since approval", not "since last scan".

Tools that were never part of an approval fall back to the legacy scan-hash check; a suspect tool there is blocked unconditionally.

Monitoring

MCP tool calls appear in the Command Center and in the trace explorer as the MCP_TOOL_CALL trace type, with metrics for total and blocked tool calls, active vs. failing servers, and pending approvals.

Next Steps

• MCP Servers — Server registration and management
• Tool Policies — Fine-grained tool governance
• API Reference: MCP — Complete MCP endpoint documentation
• Quickstart — General onboarding guide