oxynote/docs/ai.md

AI assistant and MCP server

Oxynote has two AI features. Both are optional, and the rest of the app works fine without them.

• The AI assistant is a chat inside the app. It reads and edits your documents for you.
• The MCP server lets outside AI clients, like Claude Code or Claude Desktop, use the same tools on your documents.

You can turn on either one without the other. Both run inside the production image and are set up with OXYNOTE_* environment variables.

Setting up the AI assistant

The assistant is off by default. To turn it on, pick a provider, give it credentials and restart the container.

Here is a minimal setup for Anthropic:

OXYNOTE_AI_ASSISTANT_PROVIDER=anthropic
OXYNOTE_AI_ASSISTANT_MODEL=claude-opus-4-6
OXYNOTE_AI_ASSISTANT_API_KEY=sk-...

The model line is optional. Leave it out and Oxynote picks the provider's strongest supported model.

Want to switch providers later? Change the variables and restart the container. That is all it takes.

Note

The provider variable is the on switch. If you set any other OXYNOTE_AI_ASSISTANT_* variable without it, the container refuses to boot.

Choosing a provider

Oxynote is not tied to one vendor. Five providers are supported:

Provider	Credentials	Default model
anthropic	an API key, AWS Bedrock or Google Vertex	claude-opus-5-5
openai	an API key	gpt-5.1
google	an API key	gemini-2.5-pro
ollama	none, but OXYNOTE_AI_ASSISTANT_BASE_URL must point to your server	llama3.3:70b
openrouter	an API key	anthropic/claude-opus-5.5

Picking a model

The assistant does all of its work through tools, against a large document schema. A model that calls tools badly does not just give weaker answers. It makes the assistant look broken.

So Oxynote checks your model at boot and puts it in one of three groups:

• Full strength. The assistant runs normally.
• Runs with a warning. The assistant works, but the log warns you about the model's limits.
• Not supported. Any model missing from the table below. The assistant turns off and logs a warning. The rest of Oxynote still boots.

Provider	Full strength	Runs with a warning
anthropic	claude-fable-5-1, claude-fable-5, claude-opus-5-5, claude-opus-5, claude-opus-4-6	claude-sonnet-5-5, claude-sonnet-5, claude-sonnet-4-6
openai	gpt-5.1, gpt-5	gpt-5-mini
google	gemini-3-pro-preview, gemini-2.5-pro	gemini-2.5-flash
ollama	none	llama3.3:70b, qwen3:32b
openrouter	the full-strength models above, with a vendor prefix	the warning models above, with a vendor prefix

On OpenRouter, a model ID looks like anthropic/claude-opus-5.5 or openai/gpt-5. OpenRouter writes Claude versions with a dot, not a dash.

Using an OpenAI-compatible server

Many tools speak the OpenAI chat-completions protocol: local inference servers, gateways and hosted compatibility layers. To use one, set the provider to openai and point OXYNOTE_AI_ASSISTANT_BASE_URL at it.

For Azure OpenAI, also set OXYNOTE_AI_ASSISTANT_AZURE_API_VERSION.

Reaching Claude through AWS Bedrock or Google Vertex

The anthropic provider can also reach Claude through your cloud account.

• AWS Bedrock. Set OXYNOTE_AI_ASSISTANT_BEDROCK_REGION. Leave the key variables empty to use the usual AWS credential chain.
• Google Vertex. Set OXYNOTE_AI_ASSISTANT_VERTEX_PROJECT_ID. Leave the service account empty to use application default credentials.

Where conversations are stored

If OXYNOTE_VALKEY_DSN is set, conversations are kept in Valkey. Otherwise they live in memory, and a restart clears them.

All assistant variables

Variable	What it does
OXYNOTE_AI_ASSISTANT_PROVIDER	anthropic, openai, google, ollama or openrouter. Leave it unset to turn the assistant off.
OXYNOTE_AI_ASSISTANT_MODEL	A model ID from the table above. Defaults to the provider's default.
OXYNOTE_AI_ASSISTANT_API_KEY	The vendor's API key.
OXYNOTE_AI_ASSISTANT_BASE_URL	Overrides the provider's endpoint. Required for ollama.
OXYNOTE_AI_ASSISTANT_MAX_TOKENS	The longest a single reply can be. Default 64000.
OXYNOTE_AI_ASSISTANT_REQUEST_TIMEOUT	How long one request to the provider may take, as a Go duration. Default 10m.
OXYNOTE_AI_ASSISTANT_SUMMARY_MODEL	The model that summarises long conversations. Pick a cheaper one to save money. Defaults to the main model.
OXYNOTE_AI_ASSISTANT_AZURE_API_VERSION	Targets Azure OpenAI. openai only.
OXYNOTE_AI_ASSISTANT_BEDROCK_REGION, _BEDROCK_ACCESS_KEY, _BEDROCK_SECRET_ACCESS_KEY, _BEDROCK_SESSION_TOKEN	Reaches Claude through AWS Bedrock. anthropic only.
OXYNOTE_AI_ASSISTANT_VERTEX_PROJECT_ID, _VERTEX_REGION, _VERTEX_SERVICE_ACCOUNT_JSON	Reaches Claude through Google Vertex. anthropic only.

Connecting an AI client over MCP

Oxynote is also a remote MCP server. Claude Code, Claude Desktop and other MCP clients can read and edit your documents with the same tools the assistant uses. They can also browse documents as resources.

The MCP server does not need the assistant. You can use it on its own.

Before you start

MCP needs a secure address. OXYNOTE_PUBLIC_URL must use https://, or a loopback host such as localhost. On a plain http:// LAN address, MCP stays off.

Adding Oxynote to Claude Code

1. Add the server, using your own domain:

   claude mcp add --transport http oxynote https://oxynote.example.com/core/api/mcp
   

2. In Claude Code, open the /mcp menu and pick oxynote. Your browser opens Oxynote's sign-in page.

3. Approve the client on the consent page.

That is it. Claude Code can now work with your documents.

You can see and revoke connected clients at any time in the app's settings.

How access works

• The endpoint is <OXYNOTE_PUBLIC_URL>/core/api/mcp, over streamable HTTP.
• It is protected by OAuth 2.1. Clients register themselves, and you approve each one on a consent page.
• A token works only inside your organization. It carries the documents:read, documents:write and data-sources:read scopes.
• Write tools run without asking the server for confirmation. Your client is the one that should ask you. Destructive tools are marked as such, so the client knows when to ask.