Skip to main content
Version: 0.1.0

MCP Servers Overview

Expose your RaisinDB data and functions as Model Context Protocol (MCP) servers that AI agents and MCP-capable clients connect to.

What is an MCP server?​

Model Context Protocol is an open standard that lets AI agents call tools and read resources over a uniform JSON-RPC interface. RaisinDB can serve your content and server-side logic as one or more MCP servers — you declare a server as content (a raisin:McpServer node) and the database handles the protocol, tool generation, authentication, and dispatch.

You declare what a server exposes; RaisinDB does the rest:

  • Auto data tools — generated from your NodeTypes (query, get, search, create, update, delete nodes). No code.
  • Custom tools — your own functions exposed as tools.
  • Resources — your nodes as readable, subscribable MCP resources (including raw binary assets).
  • Interactive widgets — a tool can return an inline HTML mini-app the host renders, and call your tools back on a click. See Interactive Widgets.

A repository can hold many servers, each with its own identity, policy, and access rules.

Going the other way?

This page is about RaisinDB serving tools. To let your agents call tools on somebody else's MCP server, see Connecting to External Servers.

The endpoint​

Each server is served over the MCP Streamable HTTP binding at a branch-aware URL:

POST /mcp/{repo}/{branch}/{slug}
  • {slug} is the server node's slug property.
  • {branch} makes it publish-aware — clients hit main (or your live branch) by default; an editor agent can target a working branch by changing the segment.
  • The body is one JSON-RPC 2.0 message (initialize, tools/list, tools/call, resources/*).

How it fits together​

Every tool runs under the caller's row-level security — a tool can never read or write what the caller couldn't.

Quickstart​

The builtin raisin-mcp package provisions an mcp workspace in every repository. Create a public server there:

curl -X POST \
  http://localhost:8080/api/repository/myapp/main/head/mcp/catalog \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "raisin:McpServer",
    "properties": {
      "name": "Catalog",
      "slug": "catalog",
      "version": "1.0.0",
      "instructions": "Query the product catalog.",
      "public": true,
      "data": { "workspaces": ["products"], "operations": ["query_nodes", "get_node", "search_nodes"] }
    }
  }'

Then talk to it:

# Initialize the session
curl -s http://localhost:8080/mcp/myapp/main/catalog \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}'

# List the generated tools
curl -s http://localhost:8080/mcp/myapp/main/catalog \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tools/list returns the data tools generated from the policy — here query_nodes, get_node, and search_nodes.

Indexing delay

A brand-new raisin:McpServer is discovered through an indexed query that settles a moment after the write. If the first call returns "no raisin:McpServer with slug …", retry after a short pause. In the normal publish flow this is a non-issue — the index is built by the time you merge to your live branch.

Next steps​