Cobenian Steward MCP Server

Connect AI tools like Claude Desktop to the Advisor and your Steward business data.

What is MCP?

The Model Context Protocol (MCP) lets AI applications connect to external data sources and tools. With the Steward MCP server, you can use Claude Desktop (or any MCP-compatible client) to talk to the Advisor and query your business data using natural language.

The server exposes two groups of tools over one endpoint: the Advisor tools (advisor_*) — the Advisor's own findings, grounded Q&A, and one-tap capture, which mirror the Advisor REST API 1:1 and are how the Companion connects — and the domain-data tools for reading the underlying clients, calendar, invoices, and knowledge base. Each tool declares the permission it needs; calls without it are refused.

Setup with Claude Desktop

1. Generate an API key in Settings → API Keys in the Steward dashboard.

2. Open Claude Desktop settings and add this to your MCP configuration:

{
  "mcpServers": {
    "steward": {
      "url": "https://steward.cobenian.com/mcp",
      "headers": {
        "Authorization": "Bearer ovst_your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop. You'll see Steward tools available in your conversations.

Authentication

The MCP server uses the same API keys as the REST API. Include your key as a Bearer token:

Authorization: Bearer ovst_your_key_here

API keys are scoped to your account. All tool calls return only your account's data.

Response Shape & Pagination

Tool results are returned as JSON text inside the standard MCP content array. Tools that return a list of items wrap them in an {items, meta} envelope so you can page through large result sets — identical to the REST API's meta, just alongside items instead of data:

{
  "items": [...],
  "meta": {
    "total": 137,
    "count": 20,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Every list tool accepts the same two pagination arguments:

Argument	Type	Description
limit	integer	Page size. Default 20 (25 for get_invoices). Clamped to 1..100.
offset	integer	Number of items to skip. Default 0. Clamped to >= 0.

The meta fields mean: total = all matching items (ignoring limit/offset), count = items in this page, limit/offset = the effective values applied, and has_more = whether another page exists (offset + count < total). Page by increasing offset by limit until has_more is false.

Breaking change: list tools now return an {items, meta} object. They previously returned a bare JSON array — update any client that indexed the result directly to read items instead.

Available Tools

Advisor

The Advisor's own tools. Every one — read and write — requires the read:advisor permission (there is no separate write scope, by design, so a Companion key keeps working). They read and write only the Advisor's own data and never send anything to clients. These mirror the Advisor REST API 1:1.

Core Data

Knowledge base

Example Request

Ask the Advisor a question (requires read:advisor):

curl -X POST https://steward.cobenian.com/mcp \
  -H "Authorization: Bearer ovst_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "advisor_ask",
      "arguments": {"question": "Which clients are going quiet?"}
    }
  }'

Rate Limits

100 requests per minute per API key, shared with the REST API.