Documentation

Connect idz to Claude Code, Cursor, Codex, or Claude Desktop

The idz MCP server gives your coding agent direct access to your ideas, groups, and specifications. Browse them, add snacks, pull a specification, and start building without leaving your editor or terminal.

idz runs a hosted MCP server at https://mcp.idz.app/. There is nothing to install and nothing to run locally. Most clients sign you in through your browser, so there is no key to paste anywhere.

You will need an idz account. Sign in at idz.app first. The Free plan includes MCP server access and unlimited specification generation through MCP.

Claude Code

One command. Run it anywhere:

claude mcp add idz --scope user --transport http https://mcp.idz.app/

User scope makes the connection available in every project instead of only the directory you happened to be in. On first use Claude Code opens a browser window so you can approve access.

Codex

codex mcp add idz --url https://mcp.idz.app/
codex mcp login idz

The second command runs the browser sign in.

Cursor

Edit ~/.cursor/mcp.json on macOS, or %USERPROFILE%\.cursor\mcp.json on Windows:

{
  "mcpServers": {
    "idz": {
      "url": "https://mcp.idz.app/",
      "type": "http"
    }
  }
}

Claude Desktop

Claude Desktop will not take a remote HTTP server directly, so the config bridges through mcp-remote, which runs the browser sign in on first connect. Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows: 

{
  "mcpServers": {
    "idz": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.idz.app/"
      ]
    }
  }
}

Settings, then Connectors, then Add custom connector works too. Point it at https://mcp.idz.app/.

OpenClaw

OpenClaw runs headless, so there is no browser to complete the approval step. It authenticates with an API key instead. Create one at idz.app/build/api, then edit ~/.openclaw/openclaw.json: 

{
  "mcp": {
    "servers": {
      "idz": {
        "url": "https://mcp.idz.app/",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer <idz_api_key>"
        }
      }
    }
  }
}

Replace <idz_api_key> with the key you created. Manually created keys never expire.

How sign in works

Every client except OpenClaw uses OAuth. Your client discovers the authorization server from the endpoint itself and opens a browser window asking you to approve access. Approving mints a token that lasts 30 days.

That token shows up on idz.app/build/api named after the client that created it, and you can revoke it there at any time. Expired tokens are swept automatically.

What your agent can do

Once connected, your agent has 23 tools. A common workflow is to stub an idea in idz, generate a specification, then use build_idea to kick off implementation.

Tool What it does
build_idea Fetch a specification (or draft one inline) and return a structured build prompt.
create_comment Comment on an idea, snack, or another comment.
create_idea Create a new idea in a group.
create_snack Create a snack under an idea.
create_specification_schema Create a reusable custom specification schema, a new output type (Pro).
generate_specification Fetch the brief so your agent can draft the specification using its own tokens.
get_comments Get comments on an idea, snack, or another comment.
get_group Get a single group with its members.
get_idea Get one idea with its description, snacks, comments, and group.
get_idea_specification Get a single specification with full content and token usage.
get_idea_specifications Get all completed specifications for an idea.
get_ideas_by_group List all ideas in a specific group.
get_pending_specification Check the status of in progress specification generation.
get_recent_activity Get recent comments across your ideas.
get_share_link Get the public share link for an idea.
get_snack Get a single snack with its comments.
get_specification_schema Get one specification schema by slug.
get_your_groups List groups you belong to.
get_your_ideas List ideas you authored, with search, pagination, and sorting.
list_specification_schemas List schemas you can use, both idz-provided and your own.
save_specification Persist a drafted specification to your idea.
update_idea Update an existing idea.
update_specification_schema Update a custom schema you own (Pro).

Your tokens or ours

generate_specification hands your agent the brief (the system prompt, the user prompt, and the JSON schema) and lets your agent draft the specification with its own model. idz never runs generation over MCP, so it costs you nothing against your monthly quota. Free and unlimited.

Generating in the idz web app instead uses idz's host and counts against your plan. You get portable JSON either way, which drops straight into Lovable, v0, Replit, Bolt, or any AI builder.

A worked example

Once the server is connected, this is the whole loop from a terminal:

> Use idz mcp to fetch my latest AI Guitar Tabs specification and build the idea

  idz - get_your_ideas (MCP)(searchText: "AI Guitar Tabs")
  idz - get_idea_specifications (MCP)(uuid: "88e4b702-...")
  Found 2 specifications. Let me use the latest one to build the idea.
  idz - build_idea (MCP)(uuid: "88e4b702-...", specificationId: "9")

  Ready. 3 phases, 12 tasks.

Checking it worked

Ask your client to list its MCP servers (/mcp in Claude Code). You should see idz connected. If it is not, the usual causes are a config file in the wrong location, or an approval window that was closed before you approved it. Re-running the setup command restarts the sign in.

Ready to point your agent at something worth building?

Capture the muse. Validate with peers. Build with conviction.

Get started

Keep reading