integrate with solstone

at a glance

what it is

a Model Context Protocol server inside your journal. any MCP client can use it.

address

/mcp on whichever route you turn on. on the journal's own computer: http://127.0.0.1:7659/mcp

protocol

MCP 2025-03-26 over Streamable HTTP. POST JSON-RPC and get JSON back. initialize returns an Mcp-Session-Id, and DELETE ends the session.

sign-in

OAuth 2.1 hosted by the journal (PKCE S256), or a key you create for a script

offers

9 tools. no resources, no prompts, no event stream, no stdio.

writes

only the agent's own notes. an agent can't add to, change or delete anything else in your journal.

connect an agent

1. pick where the agent runs. in your journal, open agents and choose connect an agent. the route decides the address:

   the agent runs	address	default
   on the journal's computer	http://127.0.0.1:7659/mcp	on
   on your wifi or VPN	https://<private address>:7660/mcp	off. uses a certificate from your journal's own authority, which the agents page offers for download.
   anywhere, through solstone.me	https://<8 characters>.solstone.me/mcp	off. $5/yr. the relay passes encrypted bytes through, and the journal holds the certificate.
   anywhere, at your own domain	https://<your domain>/mcp	off. the journal gets its own certificate. needs a CAA record.

2. make a pairing code for that route. it's 8 characters, works once, and expires after 10 minutes. until a code is open, the journal won't answer a sign-in from anyone.
3. add the address to your agent:

   agent	add it	then sign in
   Claude Code	claude mcp add --transport http journal <address>	type /mcp, choose journal
   Codex	codex mcp add journal --url <address>	codex mcp login journal
   Gemini CLI	gemini mcp add --transport http journal <address>	/mcp auth journal
   Claude on the web	add a custom connector in Claude's settings, with your solstone.me or own-domain address	connect it from there
   any other MCP client	add an HTTP server at the address	it should find the OAuth sign-in on its own

4. approve it. your browser opens a page served by your journal. choose what the agent may see (next section), enter the code, and connect.

what you control

every connection gets its own grant. you choose it when you approve the agent, and you can change it later in agents or with the solstone journal mcp commands.

how a grant shapes what the agent sees

• a tool that needs a kind you didn't grant is left out of the agent's tool list
• the facet and category arguments only list what you granted, so the agent is never told about a facet it can't read
• every call is checked again when it arrives, so narrowing a grant takes effect at once

for example, with transcripts only, limited to two facets, the agent is offered search like this. the facet values are the journal's ids for those facets, not their names:

{
  "name": "search",
  "title": "search the journal",
  "annotations": { "title": "search the journal", "readOnlyHint": true, "openWorldHint": false },
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "query":    { "type": "string" },
      "category": { "type": "string", "enum": ["transcripts"] },
      "facet":    { "type": "string", "enum": ["3f1c2a9e-7b4d-4e8a-9c21-5d6e0f4b7a13", "b82e4d10-1c5f-4a7e-8d3b-2f9a6c0e5d84"] },
      …
    }
  }
}

tools

all nine. "needs" is the kind you must grant before the tool is offered. days are YYYYMMDD or YYYY-MM-DD, and every list takes a limit of 1–100.

the full input schemas, and the descriptions the agent itself reads, are in registry.rs. your agent sees the same thing when it calls tools/list.

build an integration

a script on the journal's computer: use a key

create a key, then grant it what it needs. a new key can only use its own notes until you grant it more.

solstone journal mcp token create --label my-script
solstone journal mcp permission set --token my-script --category transcripts --category entities
# or: transcripts from one facet only
solstone journal mcp permission set --token my-script --category transcripts --facet work

keys work at the journal's own computer and through solstone.me. the wifi or VPN and own-domain routes take signed-in agents only. token list and token revoke --label manage them, and permission show / clear manage grants.

then talk to it like any MCP server:

# start a session, and keep the Mcp-Session-Id header it returns
curl -si http://127.0.0.1:7659/mcp \
  -H "Authorization: Bearer $JOURNAL_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-script","version":"1"}}}'

# see what this key may use
curl -s http://127.0.0.1:7659/mcp -H "Authorization: Bearer $JOURNAL_KEY" \
  -H "Content-Type: application/json" -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# call a tool
curl -s http://127.0.0.1:7659/mcp -H "Authorization: Bearer $JOURNAL_KEY" \
  -H "Content-Type: application/json" -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"query":"lease renewal"}}}'

# end the session
curl -s -X DELETE http://127.0.0.1:7659/mcp -H "Authorization: Bearer $JOURNAL_KEY" -H "Mcp-Session-Id: $SESSION"

an app or agent other people install: use OAuth

your client signs in the way the agents above do. each route hosts its own sign-in:

discovery

/.well-known/oauth-protected-resource, then /.well-known/oauth-authorization-server

registration

POST /register: dynamic client registration, or a client ID metadata document (your own https:// URL as client_id)

authorization

/authorize with PKCE S256 and the resource from the protected-resource metadata. public clients only, no client secrets.

tokens

POST /token, authorization_code and refresh_token. access tokens last 1 hour. refresh tokens rotate on every use, and reusing an old one revokes the grant.

scopes

none. the owner picks the grant on the consent page, and your client discovers the result through tools/list.

redirects

loopback (localhost or 127.0.0.1, any port), or the exact callback of a hosted agent the journal recognises. the list

design for it: /register and /authorize answer 403 until the owner has a pairing code open, so tell the owner to make one first. the grant ends 30 days after pairing however often you refresh, so handle a failed refresh by asking them to pair again.

limits

read the source

the server is open source. if you're building against it, or you want your agent to understand it, start here:

to have your agent read it, give it this: read https://github.com/solpbc/solstone-journal/tree/main/core/crates/solstone-core-mcp-endpoint and docs/MCP_OAUTH.md, then help me connect to my journal.