Spicedb

[!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 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:

   git clone https://github.com/authzed/spicedb-mcp-server.git
   cd spicedb-mcp-server
   

2. Install dependencies:

   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:

   npm run build
   # or
   yarn build
   

Usage

Running Directly

Run the server from the command line:

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:

{
  "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