Documentation

Set up USECREA

Everything you need to connect your AI agent to USECREA — from signup to your first productive session.

Prerequisites

👤

A USECREA account

Free to create — no credit card required.

🤖

An MCP-compatible AI agent

Claude Code, Claude Desktop, Cursor, Grok CLI, or any agent that supports the MCP Streamable HTTP transport.

Create an API key

API keys authenticate your agent against the USECREA MCP server. Each key can have independent read / write / delete permissions and can be scoped to specific projects.

1Log in and go to Settings → API Keys.
2Enter a name (e.g. Claude Code) and click Create.
3Copy the generated key (ucr_...) — it is only shown once.
4The API key page immediately shows a ready-made connection command for your agent — copy it directly from there.

💡

For development, use full access (read + write + delete). For production agents or shared keys, restrict to read + write only and scope to specific projects.

Connect your agent

Replace ucr_YOUR_KEY_HERE with your actual API key.

Run in your terminal:

claude mcp add usecrea --transport http https://usecreadev.clz-harz.de/mcp/ --header "Authorization: Bearer ucr_YOUR_KEY_HERE"

Allow all tools without confirmation

By default, every MCP tool call requires individual user confirmation. USECREA has 48 tools — you want to allow them all at once.

Claude Code — run once in the terminal:

claude settings add-permission "mcp__usecrea__*"

Or add manually to ~/.claude/settings.json:

Takes effect on next session start.

json{
  "permissions": {
    "allow": [
      "mcp__usecrea__*"
    ]
  }
}

Other agents

Check your agent's MCP documentation for how to auto-approve tools from a specific server. The pattern to allow is mcp__usecrea__*.

Verify the connection

Restart your agent after adding the MCP server. Then test the connection:

Claude Code

Type /mcp— “usecrea” should appear with 48 tools listed.

Any agent

Say:

List my USECREA projects.

Your agent will call list_projects and return your project list. If you get an error, check that the API key is correct and permissions are set.

The session workflow

Every USECREA session follows three phases. The MCP tools handle the rest automatically.

Startstart_working(projectId)

Always the first call. Returns a complete briefing in one call: project status, open tasks, pinned knowledge, recent activity and agent instructions. No manual context loading needed.

Example prompt:

“Start working on my USECREA project "My App".”

Duringadd_knowledge(projectId, type, title, body)

Call this immediately when you discover something important — a decision, a gotcha, a test result. Don't wait for end_session. Use type="decision" for architectural choices, type="insight" for workarounds and non-obvious facts.

Endend_session(projectId, summary, ...)

Saves a session summary, any remaining decisions/insights, updates task statuses and project status. The next agent picks up exactly where you left off — via start_working.

Example prompt:

“We're done for today. Save what we accomplished and close the session.”

The CLAUDE.md pattern

For a perfect setup — highly recommended

Without a CLAUDE.md, a fresh agent session starts cold and may explore files instead of calling start_working first. A CLAUDE.md in your project directory bootstraps the correct behavior from the very first message.

Create a file named CLAUDE.md in your project root (or any directory your agent reads on startup). Replace YOUR_PROJECT_ID with the ID from your project URL.

markdown# Project memory: USECREA

This project uses USECREA for agent memory.

## Start every session with this (mandatory)

```
mcp__usecrea__start_working("YOUR_PROJECT_ID")
```

This loads the full project briefing: status, tasks, knowledge and instructions.
Do this before reading any files or asking questions.

## Rules

- Use USECREA MCP tools to check project state — not file reads
- Save decisions immediately: `add_knowledge(projectId, "decision", ...)`
- Save gotchas and workarounds: `add_knowledge(projectId, "insight", ...)`
- End every session with `end_session(projectId, ...)` for handoff

💡

Find your project ID in the URL when viewing a project: usecreadev.clz-harz.de/projects/YOUR_PROJECT_ID

You can also set richer instructions inside USECREA itself via set_agent_instructions — those are returned automatically by start_working.

Tips & gotchas

⚠

Reload nginx after restarting containers

If the MCP server becomes unreachable after a container restart, reload nginx: the proxy caches the container IP and needs a reload to pick up the new one.

docker exec usecrea-nginx nginx -s reload

🔑

API key is shown only once

Copy it immediately when created. If lost, delete the key and create a new one — then update your agent config.

📋

Use add_knowledge immediately, not just at end_session

If the session is interrupted before end_session is called, any unsaved insights are lost. Save decisions and gotchas the moment they happen.

🔍

Find project IDs with list_projects

If you forget your project ID, ask your agent to list projects — it will call list_projects and show all IDs and titles.

List all my USECREA projects with their IDs.

🧩

Use init_project for new projects

The init_project tool creates a project with sensible elements, starter tasks and agent instructions based on a template (software, research, creative, business, general). Much faster than creating everything manually.

Create a new USECREA project for a software project called "My API". Use the software template.

Ready to connect?

Create your API key and get your agent set up in under 2 minutes.

Create API key →