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:

amsdal serve

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

Connecting Clients¶

Chatbox AI¶

Open Chatbox AI settings → MCP Servers
Add a new server:
Type: SSE
URL: http://localhost:8000/mcp/sse
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):

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

LibreChat¶

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

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:

python -m amsdal_ml.mcp_server.server_retriever_stdio

Claude Desktop Configuration¶

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

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

All MCP operations go through AMSDAL permission checks automatically.