---
title: MCP Server Setup
amsdal_docs:
  target: framework/plugins/amsdal-ml/mcp-setup.md
  nav_title: Setup
  nav_section: Framework
  nav_path: ["Plugins & Extensions", "ML", "MCP Server"]
  nav_order: 1
---

# MCP Server Setup

`amsdal_ml` provides two MCP (Model Context Protocol) servers that expose your AMSDAL data and models to AI assistants like Claude Desktop, Chatbox, and others.

## Server Types

| Server | Transport | Features |
|--------|-----------|----------|
| **Retriever (stdio)** | stdio | Semantic search tool. For local use with Claude Desktop. |
| **Model Explorer (HTTP/SSE)** | HTTP/SSE | Full model exploration, NL CRUD operations, OAuth. Automatically mounted when the plugin is registered. |

## HTTP/SSE Server (Model Explorer)

The Model Explorer server is automatically mounted at `/mcp/sse` when the `MLPluginAppConfig` is registered. No additional setup is needed — just start your AMSDAL server:

```bash
amsdal serve
```

The MCP endpoint will be available at `http://localhost:8000/mcp/sse`.

### Connecting Clients

#### Chatbox AI

1. Open Chatbox AI settings → MCP Servers
2. Add a new server:
   - **Type**: SSE
   - **URL**: `http://localhost:8000/mcp/sse`
3. If OAuth is enabled, the client will be redirected to the login page automatically

#### Claude Desktop

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

```json
{
    "mcpServers": {
        "amsdal": {
            "url": "http://localhost:8000/mcp/sse"
        }
    }
}
```

#### LibreChat

For local development, you may need to expose your server via ngrok:

```bash
ngrok http 8000
```

Then use the ngrok URL as the MCP server URL in LibreChat settings.

## Stdio Server (Retriever)

The stdio server exposes a single `search` tool for semantic search. It's useful for Claude Desktop when you only need search capabilities:

```bash
python -m amsdal_ml.mcp_server.server_retriever_stdio
```

### Claude Desktop Configuration

```json
{
    "mcpServers": {
        "amsdal-search": {
            "command": "python",
            "args": [
                "-m",
                "amsdal_ml.mcp_server.server_retriever_stdio"
            ]
        }
    }
}
```

You can pass an AMSDAL config as a base64-encoded argument:

```json
{
    "mcpServers": {
        "amsdal-search": {
            "command": "python",
            "args": [
                "-m",
                "amsdal_ml.mcp_server.server_retriever_stdio",
                "--amsdal-config",
                "<base64-encoded-config>"
            ]
        }
    }
}
```

## Authorization

The MCP server integrates with AMSDAL's permission system:

- **Class-level authorization** — checks if the user has access to a model class
- **Object-level authorization** — checks if the user can access specific records
- **OAuth** — authenticates MCP clients and maps tokens to AMSDAL users (see [OAuth](mcp-oauth.md))

All MCP operations go through AMSDAL permission checks automatically.
