Connect an AI Client to Your Workspace with MCP

An Oyren MCP server is a URL you paste into Claude, Cursor, or any other MCP client. Once connected, that client can read and write the files in your workspaces and track its work on the project boards you give it — without you copying anything back and forth.

You manage them under Settings → MCP servers.

Two kinds of server

Workspace files — every workspace has one

Made for you the first time you open a workspace, and there is no limit on them: one per workspace, on any plan. It gives a connected client

• Files. Browse, search, and read every file in the workspace — notes and scanned PDFs alike — and write new ones back (create_note, send_file).
• Sessions. Start another Oyren container, message it, and read what it produced.
• You. notify_owner emails you a status update or a question.

It cannot touch project boards. That is the other kind.

Project boards — the one a plan buys

Add one yourself, from a workspace's MCP panel or from Settings. It covers exactly one workspace and carries only the board tools: list boards, open tickets, move them between columns, and report progress as work lands.

Agents usually get both. At launch the workspace server is ticked for you; the project server is offered and left for you to tick, so an agent only gets board tools when the job needs them.

Project boards: what it can plan on

Boards are opt-in and assigned one by one. This is the part people trip over: a brand-new server sees no boards at all, even boards sitting in a workspace it can read. Until you tick some, list_projects comes back empty and the agent will tell you to assign one.

Two reasons it works that way. An agent that can see every board in a busy workspace will pick the wrong one. And an assignment is a deliberate act — you decide what a connected client is allowed to reorganise.

Assign them from the boards link on the project server's card in Settings, or from the workspace's MCP panel. An agent can also create its own board with create_project, which assigns itself so it can immediately use what it made.

What your plan includes

File access is not rationed: every workspace gets its own server on either plan, automatically.

What Max buys is boards. On free you get one project server and you choose which workspace it sits in — the others will say so in their MCP panel and offer to move it there. On Max you can give every workspace its own. Either way a workspace holds at most one project server, so an agent never sees the same board tools twice.

If you already have more project servers than your plan includes, you keep them. The limit only applies when you add a new one.

Connecting a client

Claude Code

Copy the ready-made command from the server's card — it already carries your URL and token:

claude mcp add my-workspace --transport http https://oyren.ai/api/mcp/<server-uuid> \
  --header "Authorization: Bearer <your-token>"

Claude Desktop

Claude Desktop authenticates remote MCP servers over OAuth rather than a static header. Add the server URL under Settings → Connectors → Add custom connector and approve the Oyren sign-in when it opens. There is no token to paste.

Cursor

Add the server to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "oyren": {
      "url": "https://oyren.ai/api/mcp/<server-uuid>",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Codex

Add the same URL and Authorization header to the mcp_servers block in ~/.codex/config.toml, then restart the CLI.

Gemini

Add the server under mcpServers in ~/.gemini/settings.json, using the URL and bearer token from the card, then restart the CLI.

ChatGPT

ChatGPT connects to remote MCP servers over OAuth. Add the server URL as a connector in settings and approve the Oyren sign-in — as with Claude Desktop, no token is pasted.

Your token

The token is shown once, when the server is created. If you lose it, rotate it from the card — rotating invalidates the old one, so any client still using it will need the new value. Clients that connect over OAuth never see a token at all.

When something isn't working

• The client connects but has no tools. It is almost always the token: a bearer that doesn't match returns 401 before any tool is listed.
• list_projects is empty. No boards are assigned to that server yet. Tick some in Settings.
• A board is refused. It exists, but it is not assigned to this server. Assignment is per server, not per workspace.
• You can't tick another board. You are at your plan's per-server limit. Unassign one, or upgrade.
• The agent can read files but sees no boards. It has the workspace server and not the project one. Add a project server to that workspace, then tick it at launch.
• A workspace shows no project server. On free, your one project server is in a different workspace. The panel names it and offers to move it here; Max gives every workspace its own.
• A second project server for one workspace is refused. That is the rule on every plan — two would give an agent the same eight board tools twice.