Tupshar exposes all document operations as MCP (Model Context Protocol) tools, letting Claude and other MCP-compatible clients read, write, search, and manage your documents directly.

Transport


Protocol	JSON-RPC 2.0 over HTTP
Endpoint	`https://api.tupshar.housecarl.cloud/mcp/v1`
Auth	`Authorization: Bearer tupk_…` (same API key as the REST API)

Three HTTP methods are used on the same path:

POST /mcp/v1 — send JSON-RPC requests
GET /mcp/v1 — SSE keepalive for the session
DELETE /mcp/v1 — tear down a session

JSON-RPC Methods

Method	Purpose
`initialize`	Establish a session and negotiate capabilities
`tools/list`	List available tools
`tools/call`	Invoke a tool

Available Tools

Tupshar provides 16 MCP tools.

File Operations

Tool	Required args	Notes
`tupshar_file_create`	`filename`, `contents`	Optional: `tags`, `properties`
`tupshar_file_get`	`id`	Returns document and metadata
`tupshar_file_update`	`id`, `etag`, `filename`, `contents`	`etag` is required — pass the current ETag from a prior `file_get`/`file_create` (optimistic concurrency)
`tupshar_file_delete`	`id`	Returns `{"deleted": true}`
`tupshar_file_exists`	`id`
`tupshar_file_list`	—	Paginated
`tupshar_file_stats`	`id`	Returns `token_count`, `unique_terms`, and top terms
`tupshar_file_score`	`id`, `query`	Per-term BM25 breakdown for `query` against the document
`tupshar_file_retokenize`	`id`	Re-index a document
`tupshar_file_set_properties`	`id`, `properties`	Optional `merge` (default `false` = replace the property map; `true` = merge)
`tupshar_file_add_link`	`id`, `target_id`	Optional: `rel`
`tupshar_file_remove_link`	`id`, `target_id`

Query Operations

Tool	Purpose
`tupshar_query_by_filename`	Search documents by filename pattern
`tupshar_query_by_token`	Full-text BM25 search
`tupshar_query_by_tag`	Find documents by tag
`tupshar_query_by_property`	Find documents by property key/value

Arg names match the REST API: use filename and contents (not name/content); document identifiers use id (ULID).

Example: tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tupshar_query_by_token",
    "arguments": {
      "token": "planning review"
    }
  }
}

Another example — creating a document:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tupshar_file_create",
    "arguments": {
      "filename": "meeting-notes.md",
      "contents": "# Q3 Planning\n\nAction items...",
      "tags": ["planning", "q3"]
    }
  }
}

Configuring an MCP Client

Point your MCP client at the Tupshar endpoint with your API key as a Bearer token. The exact configuration syntax varies by client; the canonical values are:

Endpoint URL: https://api.tupshar.housecarl.cloud/mcp/v1
Transport: HTTP (JSON-RPC 2.0 over POST)
Auth header: Authorization: Bearer tupk_<your-key>

For Claude Desktop and similar clients, consult their documentation for how to register a custom MCP server with a URL and auth header. Once connected, all 16 Tupshar tools will appear in the tool list.

Troubleshooting

401 Unauthorized — The Authorization header is missing or the key is wrong. Verify you are sending Bearer tupk_… with the full key.

403 quota_exceeded — You have hit your document or storage quota. Delete unused documents or request a quota increase.

429 rate_limited — Over 60 requests/min. Respect the Retry-After header.

For the full error reference see @/docs/reference/errors.md. For the underlying REST API see @/docs/integration/http-api.md.