<p align="center">
  <h1 align="center">@palveron/mcp-server</h1>
  <p align="center">Official Palveron MCP server — advisory AI-governance checks for MCP hosts and coding agents</p>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@palveron/mcp-server"><img src="https://img.shields.io/npm/v/@palveron/mcp-server.svg?style=flat-square&color=cb3837" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@palveron/mcp-server"><img src="https://img.shields.io/npm/dm/@palveron/mcp-server.svg?style=flat-square" alt="npm downloads"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License: MIT"></a>
  <a href="https://docs.palveron.com/integrations/mcp"><img src="https://img.shields.io/badge/docs-palveron.com-5A67D8?style=flat-square" alt="Documentation"></a>
  <a href="https://palveron.com/early-access"><img src="https://img.shields.io/badge/status-early%20access-F59E0B?style=flat-square" alt="Early Access"></a>
</p>

---

> **⚡ Early access.** Palveron is launching soon and access is currently invite-gated. This server is fully functional — you just need a `pv_live_` key, which comes with an Early Access invite. **[Join the waitlist → palveron.com/early-access](https://palveron.com/early-access)**

Give your MCP-capable client — Claude Code, Cursor, any other MCP host — governance tools it can call **before** executing an action: policy verdicts, PII-masking results, and an audit trace for every check, all from the Palveron AI Governance Gateway.

- **Drop-in MCP server** — one binary, configure your MCP host, you're done
- **Advisory governance verdicts** — the gateway decides allow / mask / deny / hold; the agent (or your wrapping code) acts on the verdict
- **Audit trail per check** — trace IDs flow back to the Palveron dashboard
- **Built on `@palveron/sdk`** — retry, circuit breaker, typed errors out of the box

## Advisory check vs. enforced governance — which one do you need?

This package is the **advisory** path. It cannot physically stop a tool call: it answers the question "is this allowed?", and the calling agent (or your code via `check()`/`wrap()`) is expected to honor the answer. That is by design — it works with any MCP host, needs no network topology change, and gives you verdicts plus audit traces immediately.

**Enforced, non-bypassable governance** for MCP tool calls is a different product surface: the **Palveron remote MCP proxy**. There you register the *target* MCP server in the Palveron dashboard and point your IDE at `POST {gateway}/api/v1/mcp/proxy/{server_id}` instead of the target — every `tools/call` then structurally passes through policy checks, approval holds, and drift detection before it can reach the target server. No cooperation from the agent required.

| | This package (`@palveron/mcp-server`) | Remote MCP proxy |
|---|---|---|
| Model | Voluntary pre-flight check | In-path enforcement |
| Can a call bypass it? | Yes — enforcement depends on the caller honoring the verdict | No — the proxy sits between client and target server |
| Setup | `npx`, one env var | Register the target server in the dashboard, point the IDE at the proxy URL |
| Use it when | You want verdicts + audit traces inside any MCP host, or wrap tool calls programmatically | You need governance that agents cannot skip |

See the [MCP setup guide](https://docs.palveron.com/mcp/setup) for the enforced path.

## Installation

```bash
npm install -g @palveron/mcp-server
# or use directly via npx
npx @palveron/mcp-server
```

## Quick Start

> The `pv_live_…` key in the examples below requires an **Early Access** invite — [request one here](https://palveron.com/early-access). Once you have a key, everything works out of the box.

### Claude Code

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "palveron": {
      "command": "npx",
      "args": ["@palveron/mcp-server"],
      "env": {
        "PALVERON_API_KEY": "pv_live_xxx",
        "PALVERON_BASE_URL": "https://gateway.palveron.com"
      }
    }
  }
}
```

### Other MCP hosts

Any MCP-capable host can launch the server via the `palveron-mcp` binary:

```bash
PALVERON_API_KEY=pv_live_xxx palveron-mcp
```

## Tools exposed via MCP

| Tool | Purpose |
|------|---------|
| `palveron_check` | Check a tool call against governance policies before execution. Returns the decision (`PASSED`, `BLOCKED`, `MODIFIED`/`REDACTED`/`ANONYMIZED` with the sanitized input, `PENDING_APPROVAL`, …), whether the call may proceed, findings, and the audit trace ID. |
| `palveron_status` | Governance status and diagnostics — gateway connectivity, circuit-breaker state, configured local lists. |
| `palveron_policy_list` | List the project's active policies so the host can explain its decisions. |

## Configuration

The server reads its configuration from environment variables. The MCP host sets them; you never put secrets in code.

| Variable | Required | Description |
|----------|:--------:|-------------|
| `PALVERON_API_KEY` | yes | API key (`pv_live_…`) — comes with an [Early Access invite](https://palveron.com/early-access) |
| `PALVERON_BASE_URL` | no | Override the gateway endpoint (default: `https://gateway.palveron.com`) |
| `PALVERON_FAIL_OPEN` | no | `true` = allow tool calls when the gateway is unreachable (default: `false`, fail-closed) |
| `PALVERON_LOG_LEVEL` | no | `debug` / `info` / `warn` / `error` / `silent` (default: `info`) |
| `PALVERON_ALWAYS_BLOCK` | no | Comma-separated tool names that are always denied locally, without a gateway call |
| `PALVERON_ALWAYS_ALLOW` | no | Comma-separated tool names that always pass locally, without a gateway call |

## Requirements

- Node.js **18 or newer**
- An MCP-capable client (Claude Code 0.4+, Cursor, etc.)

## Links

- **Early Access / Waitlist** — [palveron.com/early-access](https://palveron.com/early-access)
- **Documentation** — [docs.palveron.com/integrations/mcp](https://docs.palveron.com/integrations/mcp)
- **Dashboard** — [palveron.com](https://palveron.com)
- **Support** — [hello@palveron.com](mailto:hello@palveron.com)
- **GitHub** — [palveron/mcp-server](https://github.com/palveron/mcp-server)
- **Changelog** — [CHANGELOG.md](https://github.com/palveron/mcp-server/blob/main/CHANGELOG.md)

## License

[MIT](./LICENSE) — Copyright © 2026 Palveron.