# hejdar-mcp

MCP server for [Hejdar](https://hejdar.com) — runtime policy enforcement for AI agents.

This server exposes `hejdar_evaluate` as an MCP tool. Any MCP-compatible agent (Claude, ChatGPT, Cursor, custom) can call it to check whether an action is permitted by organizational policy **before** executing it.

The MCP server is a thin wrapper around the Hejdar API (`POST /v1/evaluate`). It contains no policy logic — all decisions come from your Hejdar organization's configured policies.

## Quick Start

### 1. Install

```bash
pip install hejdar-mcp
```

Or run directly with `uvx`:

```bash
uvx hejdar-mcp
```

### 2. Get your API key

Sign up at [app.hejdar.com](https://app.hejdar.com) and create an API key in **Settings → API Keys**.

### 3. Configure your MCP client

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "hejdar": {
      "command": "uvx",
      "args": ["hejdar-mcp"],
      "env": {
        "HEJDAR_API_KEY": "hejdar_sk_your_key_here"
      }
    }
  }
}
```

#### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "hejdar": {
      "command": "uvx",
      "args": ["hejdar-mcp"],
      "env": {
        "HEJDAR_API_KEY": "hejdar_sk_your_key_here"
      }
    }
  }
}
```

#### Direct (stdio)

```bash
export HEJDAR_API_KEY=hejdar_sk_your_key_here
hejdar-mcp
```

## Getting Started

1. Install: `pip install hejdar-mcp` or `uvx hejdar-mcp`
2. Get an API key — contact us at hello@hejdar.com or visit [hejdar.com](https://hejdar.com)
3. Configure your MCP client (see configuration example above)

## Tool: `hejdar_evaluate`

Evaluate an agent action against your organization's security policies.

**Input:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action_type` | string | Yes | `READ`, `WRITE`, `DELETE`, `TRANSFER`, or `EXECUTE` |
| `resource` | string | Yes | Target resource, e.g. `customer_database` |
| `agent_name` | string | No | Name of the calling agent, e.g. `hr-assistant` |
| `context` | object | No | Free-form metadata (department, user_id, reason, etc.) |

**Output:**

```json
{
  "decision": "DENY",
  "policy_id": "pol_abc123",
  "reason": "Deletion of customer data requires manager approval",
  "risk_level": "HIGH"
}
```

`decision` is one of: `ALLOW`, `DENY`, `WOULD_DENY`.

## System Prompt Pattern

For best results, add this to your agent's system prompt:

```
You have access to the hejdar_evaluate tool. Before performing any action
that reads, writes, deletes, transfers data, or executes commands on
external systems, you MUST call hejdar_evaluate first.

If hejdar_evaluate returns DENY or WOULD_DENY, do NOT proceed with the
action. Instead, inform the user that the action was blocked by policy
and include the reason provided.
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `HEJDAR_API_KEY` | Yes | — | Your Hejdar API key |
| `HEJDAR_API_URL` | No | `https://api.hejdar.com` | API base URL (for self-hosted) |

## Security

- API key is read from environment variables only — never hardcoded or exposed in tool I/O
- All inputs are validated and sanitized before forwarding to the API
- Error responses never leak internal details, API keys, or stack traces
- All API calls enforce TLS

## Development

```bash
git clone https://github.com/ARKALDA/hejdar-mcp.git
cd hejdar-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT