Set up

Spegling over MCP.

Wire your AI client into Spegling. Your notes, patterns, news, wiki, and tools become callable from Claude Desktop, your IDE agent, or any client that speaks the Model Context Protocol. Every call lands on the same Chain as a studio session.

01 Get access

Spegling is allowlist for now. Email hannu@varjosoft.com with one or two sentences on what you want to wire up. You will receive two things back:

The key is the only credential the client ever sees. Tools called over MCP run inside Spegling and never receive the operator's other secrets (Gmail tokens, etc.) — they call governed capabilities, not raw provider APIs.

02 Test the connection

Before wiring it into an agent, confirm the key works. spegling_whoami is the cheapest console identity check and returns your tenant + enclosure + corpus counts.

# Replace TENANT and KEY with the values you received.
curl -sS -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  https://api.spegl.ing/mcp/t/TENANT/ \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"spegling_whoami","arguments":{}}}'

A working call returns JSON with your enclosure id and corpus footprint. 401 means the key header is missing or malformed; 404 means the key is valid but the URL's tenant slug doesn't match the key's tenant. Mismatches always return 404 — Spegling does not leak which slugs exist.

03 Claude Desktop

Open Claude Desktop, go to Settings → Developer → Edit Config. Add the spegling entry to mcpServers. Restart Claude Desktop. The tools appear in any conversation with a small server-icon badge.

{
  "mcpServers": {
    "spegling": {
      "url": "https://api.spegl.ing/mcp/t/TENANT",
      "headers": {
        "Authorization": "Bearer sk_..."
      }
    }
  }
}

Replace TENANT with your tenant slug and sk_... with your key. If you already have other MCP servers configured, add this entry alongside them — the key is namespaced under spegling.

04 Other MCP clients

Any client that speaks the Model Context Protocol over streamable HTTP will work. The shape is always the same:

The server is stateless — there is no session token to negotiate or refresh. Each request carries its own Bearer.

For IDE agents that consume MCP through a configuration file (Cline, Continue, Cody, etc.), use the same JSON shape as the Claude Desktop block above, in whichever file the agent reads.

05 Tools

Every tool is prefixed spegling_ so it never collides with another MCP server's tools. Each call writes one row to mcp_audit on the Chain.

Read your corpus

spegling_searchHybrid search across notes, patterns, wiki, news, and journal entries.
spegling_askGrounded Q&A. Pulls relevant corpus chunks and answers, with citations.
spegling_relatedFind items related to a given text or source.
spegling_synthesizeRun a synthesis pass over a set of sources.

Notes

spegling_notesList notes, optionally filtered by query or tag.
spegling_note_readRead one note by id, with its current body and metadata.
spegling_note_createCreate a new note with title, body, tags, category.
spegling_note_updateUpdate an existing note. Creates a new revision; the old one is preserved.
spegling_note_revisionsList revisions of a note.
spegling_note_deleteSoft-delete a note (still in revisions, archived from active).
spegling_tagsList tags in use across the corpus.

Wiki

spegling_wiki_listList wiki articles in this tenant.
spegling_wiki_searchSearch wiki by query.
spegling_wiki_readRead one article by slug.
spegling_wiki_promotePromote a draft article to published.

Documents

spegling_document_ingestIngest a document (markdown, plain text) into the corpus.
spegling_document_updateUpdate an existing document by source path.
spegling_document_deleteRemove a document from the corpus.

Research + audit + identity

spegling_research_campaignStart an autonomous research run with a budget cap.
spegling_research_statusCheck the status of a running campaign.
spegling_research_findingsRead the findings from a completed campaign.
spegling_research_cancelCancel a running campaign.
spegling_auditRead recent rows from the Chain (mcp_audit) for this enclosure.
spegling_corpus_statsCounts and shape of the corpus in this enclosure.
spegling_whoamiIdentity + footprint for this tenant. Cheap console identity check.

06 Security model

The key is scoped to one enclosure inside one tenant. An enclosure is the unit of isolation: separate corpus, separate audit, separate principal roles. A key for tenant A cannot see anything in tenant B; a key for enclosure e1 cannot see enclosure e2 in the same tenant.

The client never sees provider secrets. When a tool needs to call Gmail (or any other connected service), Spegling decrypts the operator's stored OAuth token server-side and uses it. The MCP client only sees the result, not the credential.

Every call is audited. A row lands on the Chain with the tool name, a sanitized arguments summary (never the raw prompt), status, and latency. Pull the audit yourself any time via spegling_audit.

Mismatched URLs return 404, not 401. If your key is valid but the URL's tenant slug names someone else, Spegling refuses without confirming the other slug exists. The shape "this tenant exists but you cannot reach it" is not observable.

Revocation is immediate. Email Hannu to revoke. The key stops working on the next request. Issue a fresh one without changing the tenant slug or the rest of your config.

07 What goes on the Chain

Every tool call writes one row to mcp_audit in the operator's enclosure. The row carries the tool name, a sanitized arguments summary, status (ok or error), and latency. Audit is fire-and-forget on the tool's side — a failure of audit never breaks the tool call, but a tool call never escapes audit either.

This is distinct from the governed-loop ledger (loop_runs / loop_phases) the studio writes for synthesis runs. MCP tool calls are capability calls — atomic, audited, but not subject to the cross-family review pipeline. If your client uses Spegling to drive a multi-step plan, run the plan through a governed loop separately to get the per-question audit.