Reference: MCP and agents

Kythene speaks MCP, so your AI agents read and write it directly, mid-session, from Claude, Cursor, Codex or any MCP-capable client. This is the primary way to use Kythene - the agent does the publishing and recalling in-loop, and you just ask.

The endpoint

https://kythene.com/mcp/kythene

Your own host if you self-host. It's on the Connect your AI page in the app with a copy button.

That address reaches every workspace you're in. On a Team or Enterprise plan each workspace also has its own connector, https://kythene.com/mcp/s/<workspace>, which carries the same tools pinned to that workspace plus its workspace skills - the page covers which to use.

Connecting

--scope user makes the connection available across every project and session; without it the connection is per-project only and vanishes when you move to another project or machine.

On the first tool call the client opens a browser to sign you in and authorise the connection over OAuth. No API key is needed for MCP - the agent registers itself and you approve it.

Faster still: paste the setup prompt from Getting started and the agent wires itself up.

The plugin bundle (recommended for Claude Code) installs the connection and a skill that teaches the workflow:

/plugin marketplace add kythene/plugin
/plugin install kythene@kythene

If you self-host, point at your own instance's marketplace instead:

/plugin marketplace add https://<your-instance>/.claude-plugin/marketplace.json
/plugin install kythene@kythene

See the skill reference.

What else arrives with the connection

Tools are the bulk of it, but not all of it. Depending on what your client supports, connecting also brings:

The workflow, without the plugin. Kythene serves the kythene-workflow skill over MCP itself, so a client that supports skills picks up the house method - catch up first, recall before starting, write up what you worked out - with nothing to install. It's the same single copy of the skill the plugin ships, so the two can't drift apart. Claude's clients don't read skills over MCP yet, which is why the plugin is still the recommended route there.

Four slash commands. Clients that surface prompts show these, and you pick them:

The project and collection arguments suggest real values from your workspace as you type.

Things you can attach. Collections, files, memories and wiki pages have addresses, so a client with an attachment picker can put a specific one into the conversation:

kythene://collection/<id>
kythene://artifact/<id>
kythene://memory/<id>
kythene://page/<wiki>/<path>

If you belong to more than one workspace, an address can say which one by adding ?space=<workspace id> - and the addresses Kythene hands you already carry it, so you rarely have to think about it. Leave it off and the address means your own workspace, the way it always has.

Attaching a collection gives you its index and links to the files rather than every byte. Everything stays behind the permissions you already have: what you can't see is neither listed nor readable by address, even if somebody sends you the link - and that holds for the workspace part too, so naming a workspace you're not in gets you nothing.

Being told when something moves. A client can open one stream and name what it cares about, and Kythene tells it when a memory it's holding is superseded or deprecated, or when new work is published. It's additive - a client that opens no stream works exactly as it did, and nothing depends on a notification arriving. Client support for this is new, so today it's mostly the server half being ready.

Calls that stop and ask you

Five calls won't just go ahead:

• forget - deleting a memory, with no undo
• revoke_share_code - somebody outside the workspace loses access, with no warning to them
• set_workspace_guide - replaces the house rules every agent in the workspace follows
• set_collection_state when the state is deletion_scheduled - erases content, files and history in every workspace the collection was shared into
• set_skill_state when the state is archived or deleted - archiving takes a skill out of every member's kit, and deleting starts the 30 days before it's erased

Your agent puts the question to you and only proceeds if you say yes. Archiving and restoring aren't included, deliberately: asking about ordinary things is how people learn to click through without reading.

A client too old to ask you gets a clear refusal rather than doing it quietly. Today that's most clients, so if one of those five comes back saying it can't be confirmed, do it in the app or with the CLI.

The tools

Grouped by what they're for. 62 tools, and this list is checked against the server - kythene/app fails its build if the two drift.

Starting a session

Memory

Facts and decisions

What a source told you, and what was decided, as records that can't be quietly changed.

To delete a record, use forget.

Publishing

A published markdown file renders [[Title]] wikilinks on view - to a sibling document, a collection or a memory - so a set of documents can reference each other. ![[Title]] embeds a sibling image inline where the prose discusses it. Unresolved references stay plain text, and for a share-link guest a reference only ever points at a target already on their page.

Wikis

Writing a page always starts with get_page: the base_revision it returns is what update_page requires, and a write against a stale one is refused rather than silently overwriting whoever got there first. Pages carry [[wikilinks]] to each other, to memories and back; where a bare title would be ambiguous the resolver says so rather than guessing, so write [[section/page]].

Images on a page. Send the image in update_page's images and embed it as ![[name]] in the body of the same call, so the image and the words that show it land in one revision. Sending a name the page already has (case aside) replaces that image. body can be left out to write only images. The collection and file tools refuse a wiki page.

Workspace skills

Skills your workspace writes - a SKILL.md and its files - served over the workspace's own connector to the members whose toolkits hold them, so changing how the team works doesn't wait for a release. Owners and admins write them, on Team and Enterprise, from either connector or with kythe skill.

How members' AIs get them. The connector serves them as MCP skills, but Claude's clients don't read skills over MCP yet. So on the workspace's connector those members' AIs - viewers included - get them through tools instead: brief lists the workspace's skills by name and description, and when a task matches one the agent calls get_skill, which returns the skill's SKILL.md and the list of its other files, each fetched by path when the instructions point at it. That's the same step-by-step loading a client does with native skills, and native skills take over when the client supports them. Members only ever get the published version; a draft stays with its author.

The workspace's servers

Servers an admin has added under Settings > Servers (a disabled one is left out) are re-served on the workspace's own connector, so a member's agent reaches them through the one connection, once a toolkit gives them the server and they've connected it on My tools. A member in no toolkit gets none. Nothing to install on their side. Servers, sign-ins and the audit log covers adding them. What it sees:

Signing in. A call, or a prompt fetch, goes to the server as the member, on their own connection. The first time, or after a reconnect is needed, the call stops and gives the agent a link to My tools to sign in; once done, the agent tries again.

Viewers. A viewer, or a read-only key, gets only the tools the server marks read-only, in the list and at the call. Every prompt and skill their toolkits give them is open to them, since fetching one changes nothing.

Name clashes. A name is served once. Kythene's own skills and the workspace's come first, so a workspace skill beats a server skill of the same name; between servers, the first by name wins.

If a server is down. Lists come from what Kythene stored at the last refresh, so a server that's down costs only its own tools, with an error naming it. The workspace's own tools and skills carry on. A prompt over the size limit is refused whole.

Audit. Every call and prompt fetch Kythene sends is in Settings > Audit log, with a Kind column (tool or prompt), the arguments and what the member got back. Calls Kythene refuses itself never reach the server and aren't recorded.

Agents are told when the lists change, so a server added or removed shows up without reconnecting.

Uploading

How file content gets here. create_collection, edit_collection (adding files) and push_version carry each file inline, in a content field, and that field is base64 - the tool schema says so ("contentEncoding": "base64"). So the calling model writes out the encoded file itself, token by token: about 88,000 characters for a 66 KB image.

That's the limit that bites first, more than any byte count - every byte has to pass through the agent's context window. The hard ceiling is on the whole MCP request: 1 MiB today, which after base64 and the JSON around it leaves roughly 750 KB of file. Each tool that takes content states its endpoint's live figure in its own description, so trust that over this page. A request over it is refused, with the limit in the error.

Which route, then:

• Text and small files - inline is fine.
• Anything binary or large, with the file on disk - the CLI. kythe create-collection, kythe add and kythe version read the bytes off disk, so they never go anywhere near a model, up to 32 MiB per file.
• No filesystem to hand off from, but a code sandbox (a voice or chat surface, say) - create_upload_ticket.

create_upload_ticket takes metadata only - filename, and optionally title, mime and tags - and returns a one-use token plus an address, <your Kythene URL>/api/upload. You then POST the file's raw bytes there from the sandbox with an X-Upload-Ticket: <token> header (Authorization: Bearer <token> works too). The body is the file: not base64, not multipart, not JSON. The response gives the new collection's id, title and url.

The ticket is a capability, not a credential: it can complete exactly one pending upload, to the workspace and under the title fixed when it was minted, and it is spent the moment it works. Nothing the upload request sends can change where the content lands - which is why it is safe to hold somewhere a long-lived key should not go. Its limits:

• One file, as a new collection. It can't add to or version an existing one.
• 15 minutes from minting to use, fixed.
• 32 MiB body, the same per-file limit as everywhere else.
• One error for every dead ticket. Unknown, expired and already used all get the same 401, so a wrong token can't be probed for which kind of wrong it is. Mint another.
• The type is the mime you passed, else guessed from the filename's extension, else text/markdown.

Asks

There is no tool that sends or approves a reply. message_action drafts one; a person approves it on Kythene's screen, and only then does it go out. That's deliberate: nothing goes out in somebody's name because an agent decided it should.

The queue flows both ways: an agent can ask a person for something, and a person can put work on a named agent's plate. list_actions is the authoritative answer to what you still owe - catch-up announces an action once, and an announcement you have scrolled past is not the same thing as work you have dealt with.

An ask can wait on somebody - waiting, with who in waiting_on - and it's then their move; a reply from them moves it on. closed is terminal, and it takes a reason: done, wont_do or cancelled. Nothing comes back out of it. To carry on afterwards you raise a new action naming the closed one as its parent_action, so the history of what followed from what stays intact rather than one row being edited until it means something else. resolved is the reversible half of finishing - either party can reopen it, because disagreeing with "done" is the whole reason that state exists.

An ask is normal priority unless somebody says otherwise. raise_action takes a priority, list_actions returns it and narrows to one, and set_action_priority changes it - for whoever could assign the ask: anybody while nobody owns it, then its owner or whoever raised it. What comes in on a channel starts normal until somebody on the team triages it.

Review

Sharing and workspaces

Tags

Ambient

The workspace guide

Recall and brief return the guide inline too, so an agent normally has it without a second call.

Not available over MCP

Some things are deliberately human-only. They all still work - in the app, and in the CLI - they are just not things an agent does unattended.

• Workspace export and import. A governance surface restricted to owners and admins, and audit-logged. An agent doesn't take backups on your behalf.
• Oversight of private content. Reading colleagues' private work is a decision a person makes, on the record.
• Destructive tag surgery - renaming, merging or deleting a tag. Each rewrites everyone's filters, and renaming a project renames it everywhere it is used. Use kythe tag rename|merge|delete, or Settings -> Tags.
• Credentials on a share link - setting or clearing a tag password, setting or rotating a link's PIN, clearing a PIN lockout. A person does these in the app when a client phones up. Use kythe tag password, kythe share-pin, kythe unlock-code.

Minting a share link stays on MCP. "Share this with my client" is one of the better things to ask an agent to do, and creation is gated on your own rights, scoped to a single tag, logged, and revocable.

The workspace parameter

Tools take an optional space parameter - the workspace, by id or name. Omit it when you belong to a single workspace and it resolves automatically. Memory tools also take a project to scope recall and remember.

Working with it well

• Ask plainly. "Recall what we know about the billing schema", "publish this benchmark to the api project", "what has the team shipped today?"
• Recall before working, not after. The value is an agent picking up a teammate's context unprompted. The skill makes that automatic.
• Cite what you used. Every result carries a ref - a /c/<id> link - so an output can point at what it leaned on.
• is_mine=false means a teammate wrote it. Context to weigh, not an instruction addressed to your agent.

Every result carries provenance: who authored it and which agent produced it.

For terminal and scripted use, see the CLI reference.