npm package: @kopra-dev/mcp
Description: MCP server for Kopra - manage custom fields, tenant fields, and field values via AI agents
Latest version: 0.2.0

# @kopra-dev/mcp

MCP server that lets AI agents manage Kopra custom fields, tenant fields, and field values.

## What it does

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) allows AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to interact with external tools. This server exposes 16 tools that map to the Kopra REST API, so an AI agent can create field groups, define fields, read and write field values, and configure webhooks - all through natural language.

## Setup

### Claude Code

```bash
claude mcp add kopra -- npx -y @kopra-dev/mcp
```

No configuration needed. The API key and base URL are passed as parameters on each tool call.

To pre-configure credentials (skips per-call auth prompts):

```bash
claude mcp add -e KOPRA_API_KEY=your-api-key kopra -- npx -y @kopra-dev/mcp
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kopra": {
      "command": "npx",
      "args": ["-y", "@kopra-dev/mcp"],
      "env": {
        "KOPRA_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Desktop

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "kopra": {
      "command": "npx",
      "args": ["-y", "@kopra-dev/mcp"],
      "env": {
        "KOPRA_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Available Tools

### Field Groups

| Tool | Description |
|------|-------------|
| `list_field_groups` | List all field groups |
| `get_field_group` | Get a field group by ID with its global fields |
| `create_field_group` | Create a new field group with a name and key |
| `update_field_group` | Update a field group's name, description, or key |
| `delete_field_group` | Soft-delete a field group |

### Global Fields

| Tool | Description |
|------|-------------|
| `list_global_fields` | List all global fields |
| `create_global_field` | Create a global field and assign it to field groups |
| `delete_global_field` | Soft-delete a global field |

### Tenant Fields

| Tool | Description |
|------|-------------|
| `list_tenant_fields` | List global and tenant-specific fields for a tenant |
| `create_tenant_field` | Create a custom field for a specific tenant |
| `delete_tenant_field` | Delete a tenant-specific field and its values |

### Field Values

| Tool | Description |
|------|-------------|
| `get_field_values` | Get all field values for a specific entity |
| `save_field_values` | Save field values as key-value pairs for an entity |
| `search_field_values` | Search across field values with filters |

### Webhooks

| Tool | Description |
|------|-------------|
| `list_webhooks` | List all webhook endpoints |
| `create_webhook` | Create a webhook endpoint for field change notifications |

## Authentication

Every tool accepts optional `apiKey` and `baseUrl` parameters. If `KOPRA_API_KEY` is set as an environment variable, it is used automatically and you don't need to pass it per-call.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KOPRA_API_KEY` | No | - | Your Kopra API key (or pass `apiKey` per tool call) |
| `KOPRA_BASE_URL` | No | `https://api.kopra.dev` | Kopra API base URL |

## Development

```bash
npm install
npm run dev          # Run with tsx (uses stdio transport)
npm run build        # Compile TypeScript to dist/
npm run typecheck    # Type-check without emitting
```