Skip to content
projektraum
Open demoStart a project

Documentation

Work confidently in Projektraum

From the first invitation to a reviewed result. Practical guides for clients, project teams and connected AI agents.

Getting started

A project space brings work with a client together. Boards organise work within that space.

  1. Create a project space

    Create a space for your client or project in the dashboard. Give it a clear name, such as “Website redesign”.

  2. Choose a board

    Use Kanban for status columns, a project board for tables and sections, a calendar for dates or a timeline for date ranges. A project space can contain multiple boards.

  3. Invite your client

    Invite the people involved. Clients open their personal invitation link without creating an account. Set their permissions in the project settings and share each invitation only with its intended recipient.

  4. Agree on the first task

    Add a ticket with a goal, an owner and a date. The client can answer questions and review results in the project space they have access to.

Tickets and collaboration

A ticket describes a concrete result. Comments record the discussion; its status shows where the work stands.

  1. Describe the task

    Explain the desired outcome and how completion will be judged. Add an owner, priority and dates. Use a checklist for smaller steps.

  2. Keep questions on the ticket

    Use comments for questions and results. Select the right person with @ while writing. Mentions appear in their notifications; email depends on their preferences.

  3. Show progress

    Move the ticket to the appropriate column. Each board can have its own columns. Mark work complete only after review or an explicit completion report.

Files and project knowledge

Keep shared material in the project space and task-specific material on the relevant ticket.

  1. File it in context

    Use Files for briefs and shared documents. Upload task-specific files on the ticket or as a comment attachment so the context stays together.

  2. Name the version

    Use clear filenames such as “Homepage-v2.pdf” and explain changes in a comment. Client approval applies to the content at the time of the request.

  3. Read with an AI client

    An authorised MCP client can list and download files. Reading PDF or Office content depends on that client’s capabilities. Projektraum does not automatically extract the content.

Which workflow helps when?

Each area solves a different project need. You do not have to use every one for each ticket.

  1. Request → ticket

    Paste text or load a TXT/Markdown file locally into the request field. Add a goal, checklist and date. Preparation uses the first line as the title and adds questions. Review the draft before adding it to a board; this is not automatic document analysis.

  2. AI job → reviewed result

    Explicitly authorise a defined task for a particular MCP connection. Your running agent claims it and reports progress, blockers or a result. Review the result before completing the job.

  3. Client approval → decision

    Ask the client to review a particular version. Approval and requested changes remain visible on the ticket. Approval does not automatically complete the ticket.

  4. Rules and reports

    Board rules handle supported steps such as priority or assignment. Reports show progress and pending decisions. Clients see a report only after it has been shared with them.

Two concrete client projects

Follow who takes the next step and what information they need.

  1. Website: an extra phone field

    Marc asks for an optional phone field. Lara clarifies mobile behaviour and acceptance criteria. She creates a ticket, optionally authorises her running agent, reviews its result and asks Marc for approval. Only then does she decide whether to close the work.

  2. Design: lighter product images

    Sina identifies the two images and the desired change. Lara clarifies the exact version, edits the files herself and requests another approval. The change request and decision stay on the ticket. No AI agent is required.

  3. What the demo shows

    Guided examples explain the handoffs. Sample data and actions stay in the demo; they do not start real work or send messages.

Website: an extra phone fieldTry the exampleDesign: lighter product imagesTry the example

Set up MCP

MCP connects an AI client to a particular project space. The client can only use tools and data within its granted permissions.

  1. Create a connection key

    Project owners open AI/MCP settings and choose the project space. Invited clients find the connection in their project space settings. Create a clearly named key for each client.

  2. Choose permissions

    Select read only or read and write. Write access permits comments and ticket changes where your account has permission. The full key is displayed only once; store it securely.

  3. Test the connection

    Configure your client below. Then ask: “Show me the open tickets and my unread mentions in Projektraum.” First check that the correct project appears.

  4. Manage access

    Revoke unused keys in settings. Replace expired keys. Choose concise or detailed agent comments per connection.

MCP server address

https://projektraum.io/api/mcp

Use only one authentication method. Never put a key in a chat, URL or Git repository. prk_… is only a placeholder: replace it with the full key shown once at creation, not just the prefix or the ellipsis.

Claude

Create a custom connector with the server address and “No sign-in”. Under Request headers, select the built-in x-api-key header and enter only the complete prk_ key. Do not create an OAuth client ID.

URL: https://projektraum.io/api/mcp
x-api-key: prk_…

If your account does not offer suitable request headers, use Claude Code. If saved headers cannot be edited, recreate the connector with the correct settings.

Official guide
Codex

Add the configuration to ~/.codex/config.toml. PROJEKTRAUM_API_KEY contains only the key and must be available to the running Codex process.

[mcp_servers.projektraum]
url = "https://projektraum.io/api/mcp"
bearer_token_env_var = "PROJEKTRAUM_API_KEY"

Codex adds Bearer automatically. A terminal variable is not automatically available to a separately launched desktop app. Check /mcp or the MCP connection view.

Official guide
Claude Code

Merge this configuration into your working project’s .mcp.json. Set PROJEKTRAUM_API_KEY in the environment used to start Claude Code.

{
  "mcpServers": {
    "projektraum": {
      "type": "http",
      "url": "https://projektraum.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PROJEKTRAUM_API_KEY}"
      }
    }
  }
}

Preserve existing mcpServers entries. Claude Code expands the environment placeholder at startup. Approve the project configuration, then check or reconnect through /mcp.

Official guide
ChatGPT

The current Projektraum integration does not support a direct protected connection in ChatGPT Web. ChatGPT needs OAuth for this; Projektraum uses an API key here.

A prk_ key is neither an OAuth client ID nor a client secret. “No authentication” does not bypass the server’s protection. You can use Codex with the existing integration.

Official guide

Reviewed October 31, 2026

MCP for developers and agents

The endpoint uses Streamable HTTP. Call tools/list first to obtain the tools and current schemas available to your key.

  1. Read before writing

    get_project returns boards, columns and members. get_task and list_comments provide ticket context. Use IDs and status keys from responses instead of guessing. Lists support limit and offset.

  2. Retry safely

    Write operations require a new UUID request_id. On retry, reuse that ID with unchanged arguments. For ticket updates, pass task.updated_at from get_task as expected_updated_at. On a conflict, reread and reconcile changes.

  3. Descriptions and mentions

    append_task_description preserves and extends existing content. update_task with description replaces the entire description. Comments use plain text; @ plus an exact member name creates a mention. list_notifications reads notifications; mark_notification_read acknowledges them separately.

  4. Files and agent jobs

    list_files returns file IDs and source. get_file provides a private download URL valid for 60 seconds; request a new one after expiry. list_agent_jobs, claim_agent_job and update_agent_job manage work orders. Respect the claim token and lease; review requires result evidence.

Troubleshooting

Start with the specific error. A saved connector alone does not launch an agent on your computer.

  1. Connection or authentication fails

    Check the HTTPS address, complete key, expiry and revocation. For x-api-key, enter only the key; for Authorization, use Bearer, one space and the key. Do not add quotes or send both headers.

  2. Reading works but writing fails

    Check the connection’s write access and current project permissions. Archived or restricted projects may block changes. Do not broaden permissions just to work around an error.

  3. Tools are missing after an update

    Refresh the client’s tool list or reconnect. Start a new chat if needed. Claude may expose this in the connector menu; direct CLI connections can reconnect through /mcp or restart.

  4. The agent does not react automatically

    The agent must be running and poll notifications or its work orders. MCP provides project access, not an automatic launch service. A mention does not authorise arbitrary actions on the computer.