AI Client Connections to a Workspace with MCP

An Oyren MCP server provides a URL for Claude, Cursor or another MCP client. A connected client can read and write workspace files and track work on assigned project boards without manual copying between tools.

You manage them under Settings → MCP servers.

Two kinds of server

Workspace files — every workspace has one

A workspace file server is created when a workspace is first opened. There is one per workspace on any plan, with no limit on the number of workspace file servers. 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.
• Owner notifications. notify_owner emails the owner 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 server types. At launch the workspace server is selected by default; the project server is offered without selection, so board tools are attached only when the job needs them.

Project boards: what it can plan on

Boards are opt-in and assigned one by one. A new server sees no boards, including boards in a workspace it can read. Without assignments, list_projects returns an empty result and the agent asks for a board assignment.

Board assignment limits the choice of boards available to an agent in a busy workspace. It is also an explicit decision about which boards a connected client may 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.

Plan limits

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

Max changes the project board allowance. Free includes one project server assigned to one workspace. Other workspaces identify that assignment in their MCP panel and offer to move it. Max permits a project server in every workspace. Each workspace holds at most one project server, so an agent never receives the same board tools twice.

Existing project servers above the plan allowance are retained. The limit applies only to adding a new server.

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.

Authentication 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.