> ## Documentation Index
> Fetch the complete documentation index at: https://docs.the40thieves.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Connect to reliquary-tc over MCP (stdio or HTTP), discover and call tools through the triad facade, and authenticate.

reliquary-tc **is an MCP server** — its API is the [Model Context Protocol](https://modelcontextprotocol.io) (JSON-RPC 2.0) spoken over **stdio** or **Streamable HTTP**. Any MCP client (Claude Code / Desktop, Cursor, VS Code, or your own) talks to it the same way: negotiate, list tools, call tools. This is the callable reference; the [Tool Reference](https://docs.the40thieves.dev/reliquary-tc/tools.md) is the surface overview (facade + domains), and the [configuration reference](https://docs.the40thieves.dev/reliquary-tc/configuration/config-yaml.md) documents every option.

## Connect

### stdio (local, default)

The server runs on your machine over stdio — no network, no account, no key. Point any MCP client at the `npx` launcher:

```json theme={null}
{
  "mcpServers": {
    "reliquary-tc": {
      "command": "npx",
      "args": ["-y", "reliquary-tc"],
      "env": { "RELIQUARY_TC_CONFIG": "/ABSOLUTE/PATH/TO/reliquary-tc.config.json" }
    }
  }
}
```

Cursor (`~/.cursor/mcp.json`) uses `mcpServers`; VS Code (`.vscode/mcp.json`) uses `servers`. Claude Code: `claude mcp add reliquary-tc --env RELIQUARY_TC_CONFIG=/ABSOLUTE/PATH/TO/reliquary-tc.config.json -- npx -y reliquary-tc`. Or run it directly: `reliquary-tc /path/to/vault`.

### Streamable HTTP (remote)

Enable `transports.http` to serve MCP over HTTP for a remote client. A non-loopback bind **requires auth**: the config fails to load if `transports.http` is on a routable host while `auth.mode` is `none` — an unauthenticated server never binds a public address. `GET /obsidian-tc/v1/probe` is a health endpoint that returns `200` when the server is live.

## The tool API: discover, describe, call

By default `tools/list` advertises **three meta-tools** — the `triad` facade, set by `toolFacade.mode` — plus the standard `search` and `fetch` tools that ChatGPT deep research and company knowledge require. You search for a capability, inspect its schema, then invoke it. Every underlying tool also stays callable directly by name; the facade just shapes what `tools/list` advertises.

### `find_capability` — search the catalog

BM25 search over the full tool surface. Returns capability names + one-line summaries.

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "find_capability", "arguments": { "query": "read a note", "limit": 5 } } }
```

### `describe_capability` — get a tool's schema

Returns the full input schema (JSON Schema 2020-12), the required scope set, and safety hints (`readOnlyHint` / `destructiveHint`).

```json theme={null}
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "describe_capability", "arguments": { "name": "read_note" } } }
```

### `call_capability` — invoke by name

Runs the target with its arguments, through the same authorization / ACL / HITL / idempotency / rate-limit pipeline as a direct call — the target's own schema validates `args`.

```json theme={null}
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "call_capability",
    "arguments": { "name": "read_note", "args": { "path": "notes/example.md" } } } }
```

Results come back as MCP tool content — a human-readable `text` block plus `structuredContent` (the typed result). A failed call returns `isError: true` with the structured error attached, so a model can self-correct instead of seeing a protocol error.

The other `toolFacade.mode` values: `domain` (about a dozen `{ action, args }` domain tools), `flat` (the full surface advertised directly), and `auto` (picks one of the three per connecting client — provisional and superseded by setting the mode explicitly per client). See the [Tool Reference](https://docs.the40thieves.dev/reliquary-tc/tools.md) for the domain map, and [Choosing a facade mode per client](https://docs.the40thieves.dev/reliquary-tc/getting-started/mcp-clients.md#choosing-a-facade-mode-per-client) for which mode each client should use.

A separate, deployment-level setting, `toolFacade.profile`, can additionally narrow which tools are visible/callable at all — see [Tool profile](https://docs.the40thieves.dev/reliquary-tc/tools.md#tool-profile). Under the opt-in `profile: "core"`, a `find_capability` query that also matches a hidden tool says so (name + count, in a `hiddenByProfile` field); `describe_capability`/`call_capability` on a hidden tool by name answer `capability_hidden` with a reason, never a bare "not found".

## Authenticate

| `auth.mode` | Use |
| - | - |
| `none` *(default)* | Loopback only, enforced by the fail-closed interlock above. |
| `jwt` | HS256 (`jwtSecret` / `RELIQUARY_TC_JWT_SECRET`) **or** asymmetric RS256/ES256/EdDSA via an inline/file JWKS (`kid`-based rotation). Present the token as a bearer credential. |

With `auth.resource` + an `authorizationServers` entry set, the HTTP transport advertises an RFC 9728 Protected Resource Metadata document and a `WWW-Authenticate` challenge (the OAuth 2.1 resource-server role).

## Authorization, ACL, HITL

Every call — direct or via `call_capability` — passes the same gates:

* **Scopes** — each tool declares a required scope set; both `tools/list` and dispatch are filtered to the caller's scopes.
* **ACL** — per-path read / write / delete whitelists (`.obsidian/`, `.git/`, `.trash/` are always denied, case-folded); `readOnly` is a hard kill switch.
* **HITL** — destructive and `execute:*` operations require a human-in-the-loop confirmation token, so `git_commit` and `execute_command` can never fire silently.

## Choosing a vault

Tools that act on a vault take a `vault` id. It may be omitted when exactly one vault is available to the caller: the vaults a caller can see are those left after its token's vault binding and each vault's own folder ACL, so a token bound to a vault defaults to that vault; a vault the caller can read nothing in (an empty `readPaths`, or `strictReadDefault` with no `readPaths`) is not available, and `list_vaults` agrees. With more than one available vault an omitted `vault` is a `validation_error`; a caller holding `read:vault` gets the available ids in the error. An explicit `vault` is always used as given, and a bound token naming another vault is still refused.

## Errors

Failures return a typed error from the `ReliquaryTcError` taxonomy (e.g. `plugin_missing`, `embedding_provider_error`, `requires_live_obsidian`, `read_only_mode`) with a `retryable` flag — never an opaque throw. At the MCP boundary a dispatch failure surfaces as a **Tool Execution Error** (`isError: true`, human-readable text plus the structured error as `structuredContent`).

The error envelope is:

```json theme={null}
{
  "code": "acl_denied",
  "message": "path denied by folder ACL",
  "retryable": false,
  "details": { "path": "…", "op": "write" },
  "recovery": "This path is outside the folder ACL for this caller. Call inspect_acl to see which roots are permitted and retry within one of them."
}
```

`recovery` is bounded next-step guidance for the code — it names the tool to call next where one exists, and complements `retryable` (which says only *whether* a retry could help). It is selected by error code alone, so it never echoes a path, query, caller or vault back to the client. `details` is where request-specific context appears, when the raising site chooses to include it.

## See also

* [Tool Reference](https://docs.the40thieves.dev/reliquary-tc/tools.md) — the tool surface, facade modes, and the domain map.
* [Configuration](https://docs.the40thieves.dev/reliquary-tc/configuration/config-yaml.md) — transports, auth, ACL, embeddings, retrieval.
* [Quickstart](https://github.com/The-40-Thieves/reliquary-tc/blob/main/docs/QUICKSTART.md) — first run and live-bridge setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.