# SpiceDB MCP Server

> [!CAUTION]
> This is an experimental MCP server. This is only intended for educational purposes so use at your own risk.

A Model Context Protocol (MCP) server that connects to [SpiceDB](https://authzed.com/spicedb) via its HTTP API for permission management. This server enables LLMs like Claude to interact with your SpiceDB instance to query, manage, and understand your permission system.

## Features

> [!NOTE]
> Everything in this repo was almost entirely created by Claude 3.5 Sonnet. Any quirks, unusual patterns, or potential errors are direct artifacts of LLM-based generation.

- **Resources**:
  - Schema retrieval with associated object definition resources
  - Relationship queries with interactive relationship resources
  - Object definitions with detailed type information

- **Tools**:
  - Read schema with object definition resources
  - Read relationships with relationship resources
  - Check permissions with detailed authorization traces and explanations
  - Look up resources by subject with permission context
  - Look up subjects by resource with permission details
  - Write relationships with validation

## Prerequisites

- Node.js 16+
- SpiceDB instance
- SpiceDB API key

## Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/authzed/spicedb-mcp-server.git
   cd spicedb-mcp-server
   ```

2. Install dependencies:
   ```bash
   npm install
   # or
   yarn install
   ```

3. Configure your environment:

   Create a `.env` file with your SpiceDB connection details:
   ```
   # SpiceDB HTTP API endpoint (the default port for HTTP API is typically 8443)
   SPICEDB_ENDPOINT=http://localhost:8443
   # or for TLS: https://spicedb.example.com

   SPICEDB_API_KEY=your-api-key-here
   SPICEDB_USE_TLS=false
   ```

4. Build the server:
   ```bash
   npm run build
   # or
   yarn build
   ```

## Usage

### Running Directly

Run the server from the command line:

```bash
node build/index.js
# or
npm start
# or
yarn start
```

### Integrating with Claude for Desktop

1. Edit your Claude for Desktop configuration file:

   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the SpiceDB MCP server to the `mcpServers` section:

```json
{
  "mcpServers": {
    "spicedb": {
      "command": "node",
      "args": [
        "/path/to/spicedb-mcp-server/build/index.js"
      ],
      "env": {
        "SPICEDB_ENDPOINT": "http://localhost:8443",
        "SPICEDB_API_KEY": "your-api-key-here",
        "SPICEDB_USE_TLS": "false"
      }
    }
  }
}
```

3. Restart Claude for Desktop

4. View logs for Claude Desktop and SpiceDB MCP

   **macOS**: `/Users/<your username>/Library/Logs/Claude/mcp-server-spicedb.log` and `/Users/<your username>/Library/Logs/Claude/mcp.log`


## Examples

> [!NOTE]
> A SpiceDB instance with a schema and relationship data should be running with the flag `--http-enabled`

### Example Commands for Claude

#### Check a permission:

"Does user:alice have the permission view on document:report1?"

#### Find all resources a subject can access:

"What documents can user:bob read?"

#### Find all subjects that can access a resource:

"Who has edit permission on project:website?"

#### Analyze schema:

"Can you explain the permission system schema?"

#### Setup test scenarios

"Setup the following scenario by writing the appropriate relationships: there is a new role "auditor" and user jared has that role"

#### Preview compliance operations

"The project pied_piper is now deprecated. Find all users who have some form of access to it and create a comprehensive list of users and their access"

## API Reference

### Resources

- `spicedb://schema` - Get the current schema, returns both schema text and object definition resources
- `spicedb://relationships/{resourceType?}/{resourceId?}/{relation?}/{subjectType?}/{subjectId?}/{subjectRelation?}` - Query relationships with optional filters
- `spicedb://definition/{objectType}` - Get detailed definition for a specific object type

### Tools

- `read-schema` - Retrieves the current schema with object definition resources
- `read-relationships` - Queries relationships based on filter parameters, returns both text output and relationship resources
- `check-permission` - Checks if a subject has a specific permission on a resource with debug tracing and explanations of the authorization decision
- `lookup-resources` - Finds resources where a subject has a specific permission, optimized for array response formats
- `lookup-subjects` - Finds subjects with a specific permission on a resource, optimized for array response formats
- `write-relationship` - Creates, updates, or deletes a relationship with validation

### Prompts

- `lookup-resources-for-subject` - Finds resources a subject can access
- `lookup-subjects-for-resource` - Finds subjects that can access a resource
- `explain-permission-check` - Explains a permission check result
- `analyze-schema` - Analyzes the current permission schema

## Relationship Format

Relationships in SpiceDB are formatted as:

```
resourceType:resourceId#relation@subjectType:subjectId[#subjectRelation]
```

This format combines:
- Resource: `resourceType:resourceId` (the object being accessed)
- Relation: `#relation` (the relationship type)
- Subject: `subjectType:subjectId` (the actor accessing the resource)
- Optional subject relation: `#subjectRelation` (for computed subjects)

Examples:
- `document:report#viewer@user:alice` - User alice is a viewer of the report document
- `project:website#admin@group:engineering#member` - Members of the engineering group are admins of the website project
- `resource:promserver#viewer@usergroup:engineering#member` - Members of the engineering user group are viewers of the promserver resource

## MCP Connection Lifecycle

The SpiceDB MCP server implements the full Model Context Protocol connection lifecycle:

1. **Initialization Request**: When a client connects, it sends an `initialize` request containing:
   - Protocol version
   - Client information (name, version)
   - Client capabilities

2. **Server Response**: The server responds with:
   - Protocol version
   - Server information (name, version)
   - Server capabilities (resources, tools, prompts, etc.)

3. **Initialization Confirmation**: The client sends an `initialized` notification to confirm the connection.

4. **Message Exchange**: Normal operation begins with the exchange of requests and responses.

5. **Termination**: When the client disconnects, the server cleans up resources.

The server logs details about this lifecycle to stderr, which you can observe when running the server directly.

### Server Capabilities

This server provides the following capabilities:

- **Resources**: Exposes schema, relationships, and definitions as readable and navigable resources
- **Tools**: Provides tools for interacting with SpiceDB with rich responses including resources
- **Prompts**: Offers template prompts for common permission-related tasks and analysis
- **Debug Tracing**: Includes detailed authorization decision traces and explanations
- **Response Formats**: Support for both legacy and array-based SpiceDB API response formats
- **Logging**: Provides structured logging for troubleshooting and monitoring