Metadata-Version: 2.4
Name: hejdar-mcp
Version: 0.1.0
Summary: MCP server for Hejdar — runtime policy enforcement for AI agents
Project-URL: Homepage, https://hejdar.com
Project-URL: Repository, https://github.com/ARKALDA/hejdar-mcp
Project-URL: Issues, https://github.com/ARKALDA/hejdar-mcp/issues
Author-email: Hejdar <anton.renmark@hejdar.com>
License-Expression: MIT
Keywords: ai-agents,audit,mcp,policy-enforcement,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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
```

## 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
