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. On the MCP path, Palveron checks tool calls against your rules: a tool is reachable only after an admin has admitted it, and each tool has a rule such as allowed, approval required, or denied. Content-level detection of personal data in the calls does not happen on this path today.

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 approves it, admitting each tool with a rule (only admitted tools of an ACTIVE server are 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 the rules let it through, the call is forwarded to the actual MCP server. Palveron then records the call. If recording fails, the call has still been carried out and does not appear under Trace Explorer.

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 and determines each one's action and risk. It sets no rule: Palveron proposes one per tool, and an Admin decides with the approval (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: Approval (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 a successful scan an Admin approves the server (Integrations → MCP → Approve); before that, approving is locked with the reason. The approval dialog lists every discovered tool with a proposed rule; the Admin keeps or changes each one and confirms with Accept proposals (N). Approval, pausing and rejection are dedicated, logged Admin actions. This role split (Editor connects and scans, Admin approves and admits) 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

With the approval every tool gets the rule an Admin confirmed. You can add stricter rules, for example for a single agent. 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 stricter policy is an Editor action; an allowing one (ALLOW, LOG_ONLY) and deleting one are Admin actions. With agent_id, only REQUIRE_APPROVAL and DENY are accepted. See the MCP API reference for the full body.

Approval requests

When a tool call meets a REQUIRE_APPROVAL rule, or no rule applies, it is placed in the queue:

1. The coding agent's call is paused (JSON-RPC -32004, with the request id)
2. An Admin reviews the request under Approvals
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 admits a tool (with the server's approval, or one by one on the tools page), Palveron records a fingerprint over the tool's name, description and input parameters: the admitted state. On every later call the current tool surface is compared against it:

• Unchanged → the call proceeds under its rule.
• Changed since the admission (a classic rug-pull / tool-poisoning vector) → the call is blocked (-32002, APPROVED_FINGERPRINT_MISMATCH) and logged (McpToolDrift → OCSF/SIEM) until an Admin checks the current state and admits the tool again on the tools page. Resuming a paused server does not do this.

A tool that is not admitted is blocked (-32002, TOOL_NOT_RELEASED).

Monitoring

MCP tool calls appear in the Command Center and in the Trace Explorer with the type MCP_TOOL_CALL, with metrics for total and blocked tool calls, active servers, servers whose last scan failed, and pending approval requests.

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