Connect an AI client with MCP

NextOS speaks the Model Context Protocol (MCP), the open standard that lets an AI assistant like Claude, or an editor like Cursor or VS Code, call a set of tools and read a set of resources from an outside application. There are two separate MCP servers, built for two different audiences.

Two servers, two audiences

The public server is read-only and needs no account. It answers questions about this product itself - what it is, what it can do, its public case studies - so any AI assistant can look it up the same way it would look up any other public web page. There is nothing private behind it, and nothing to sign in to.

Your files server is the one this guide is mostly about. Once you're signed in, your NextOS account has its own filesystem - notes, documents, anything you've saved. This server lets an AI client you control read, and optionally write, those files directly, the same way your in-app assistant does. It requires a key that only you can create, and it only ever sees the files and actions you've allowed it to see.

If you just want an assistant to know about NextOS as a product, you don't need to read further - the public server needs no setup. The rest of this guide covers connecting your own files.

Setting it up

1. Open Settings > Developer.
2. Find the Connect your tools card.
3. Choose a key to use, or create a new one right there. A freshly created key defaults to read-only access (it can look at and list your files, but not change them); flip on Allow write access if you also want the client to be able to write, edit or patch files. You can always come back and create a second, more permissive key for a client you trust more, and keep a stricter one for everything else.
4. The card shows ready-to-use configuration for Claude Desktop, Claude Code, Cursor, and VS Code - copy the one for whichever client you're setting up and drop it into place following that client's own instructions for adding an MCP server. Each one already has your address and your key baked in.
5. Use the Test connection button on the card to confirm the key works and see exactly which actions it's currently allowed to perform, before you go set up your client.

A key's secret is shown to you exactly once, at the moment it's created. If you lose it, don't worry about trying to recover it - just create a new key (and consider removing the old one).

What the assistant can actually do

Once connected, a client sees a small, fixed set of actions scoped to your files: reading a file, listing what's in a folder, and - only if you've allowed write access - creating or changing a file, or making a targeted edit to one. Nothing outside your own files is ever reachable, and no action is available that your key wasn't given permission for.

Staying in control

Your key, your rules. Every key you create carries its own permissions. A read-only key can never be tricked into writing a file, no matter what the connected client asks for - the limit is enforced on our side, not the client's.

Team plans add another layer. If your account belongs to a team with its own governance rules, those rules apply on top of your key's own permissions, and the stricter of the two always wins. A team admin can, for example, prevent write access entirely for every member's keys, or block a particular kind of change outright regardless of what any individual key allows. If your workspace has rules like this configured, an attempted action that runs into one comes back with a clear explanation of why it was refused, rather than silently failing or quietly asking someone to approve it later - actions that would normally pause for a person's sign-off aren't supported through this connection, so a rule like that blocks the action outright instead.

Rate and spend limits carry over. Whatever request-rate or spend limits you set when creating a key apply here exactly as they would anywhere else the key is used.

Rotate keys periodically. If your plan enforces a key-rotation schedule for keys used by a team, an overdue key stops working until it's rotated in Settings, exactly as it would for any other use of that key. For a personal key, rotating regularly whenever a connected tool or device changes is good hygiene even when nothing requires it.

Revoke anytime. Removing or revoking a key in Settings takes effect immediately - any client using it loses access on its very next request.

Troubleshooting

• "Unauthenticated" or a similar rejection almost always means the key was revoked, mistyped, or never actually saved into the client's configuration - use the Test connection button in Settings first to confirm the key itself works before checking the client.
• An action is refused as "not allowed" means your key's own permissions, or your team's rules, don't permit it - check the tool list shown by Test connection, or ask a team admin if you're on a team plan.
• A write is refused specifically because of what it targets (a particular file or folder, for instance) means a team rule is targeting that specific case - this is expected behavior for accounts under stricter governance, not a bug.