Get started
Protocol

Getting Started

Get ContextQ running with your AI agent in under five minutes. Prefer to let your agent do it? Hand it one prompt.

  1. Before00

    Prerequisites

    • A terminal with curl and bash (macOS, Linux, or WSL / Git Bash on Windows) for the Claude Code installer
    • An MCP-compatible AI agent: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, or Cline

  2. Step01

    Create an account and connect Claude Code

    Sign up at app.contextq.dev — no credit card, and every new account starts with a 14-day Pro trial. Then install the ContextQ plugin for Claude Code (v2.1.268 or later) with the installer. It asks for one approval in your browser and hands the key straight to Claude Code, so there is nothing to copy or paste.

    After you verify your email, the dashboard's Connect an Agent screen also shows your first API key once, with a ready-to-copy claude plugin install command. Copy it then; the full key is not shown again.

    terminal 
    curl -fsSLo install.sh https://app.contextq.dev/plugin/install.sh
shasum -a 256 -c <(curl -fsSL https://app.contextq.dev/plugin/install.sh.sha256)
bash install.sh

    Or hand Claude Code this one line and let it run the install itself:

    prompt 
    Install ContextQ for this machine and this repository. Follow https://app.contextq.dev/install.md exactly. Pause only for browser authorization or an ambiguous workspace. Never ask me to paste an API key.

    Other agent

    Using another agent? Cursor, Codex, Gemini CLI, Windsurf, Cline and manual configs authenticate with an API key created in the dashboard under Settings > API Keys, available on every plan (Free includes 3 active keys). Keep that key secret: do not commit it to version control, store it in an environment variable or your agent's local config.

  3. Step02

    Add the MCP server to your agent

    Installed the Claude Code plugin in step 1? It already carries the MCP server, so skip to step 3. Otherwise, ContextQ exposes its tools through the Model Context Protocol: add the server configuration to your agent of choice.

    Claude Code

    Add to ~/.claude/settings.json or a project-level .mcp.json:

    .mcp.json 
    {
  "mcpServers": {
    "shared-context": {
      "type": "http",
      "url": "https://app.contextq.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

    Cursor

    Add to .cursor/mcp.json in your project root:

    .cursor/mcp.json 
    {
  "mcpServers": {
    "shared-context": {
      "url": "https://app.contextq.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

    Other agents

    Codex, Gemini CLI, Windsurf, and Cline all support MCP. Point them at the same streamable HTTP endpoint, https://app.contextq.dev/mcp, with your API key as a Bearer token in the Authorization header. Consult your agent's MCP documentation for the exact config file location. The canonical, always-current install contract lives at app.contextq.dev/install.md.

  4. Step03

    Save your first context

    In your AI agent, ask it to save a piece of knowledge ("remember that deploys use Docker Compose"). The agent calls the ctx_save tool; with the Claude Code plugin, the /contextq:memory skill guides the same loop.

    tool call 
    # What the agent sends
ctx_save { "name": "deploy", "type": "project", "workspace": "acme",
           "description": "Deploy uses Docker Compose on production server", "content": "..." }
  saved · id 1042 · workspace acme

  5. Step04

    Search context

    Use ctx_search to find prior decisions, conventions, and patterns across all your projects. The search combines full-text and vector similarity for accurate results even on vague queries.

    tool call 
    # Search across all projects
ctx_search { "query": "deployment infrastructure" }
  3 entries across 2 projects

    Your agent can now retrieve context automatically when working on related tasks. Knowledge saved once is available everywhere.

Available tools

The hosted MCP server exposes the 16 tools below; the full reference has their parameters. Your agent discovers them automatically once connected.

ToolDescription
ctx_saveSave a new context entry: reference, feedback, project note, incident, lesson, user profile or synthesis.
ctx_searchSearch context entries with hybrid full-text and vector search, ranked by relevance.
ctx_getGet a single context entry by its ID.
ctx_listList context entries filtered by workspace, project, type, tag or scope.
agent_bootOne call at session start: last checkpoint, open tasks, latest handoff, relevant lessons and facts.
agent_checkpointSnapshot the agent's working state so a restart can resume from exactly there.
agent_handoffGenerate an end-of-run handoff (TL;DR, in progress, next steps) for the workspace. LLM-written, so it needs a paid plan; on Free it returns a skipped handoff.
agent_handoff_saveSave a handoff you wrote yourself, keyed so a re-run updates the same entry. No LLM, available on every plan.
goal_addAdd a node to the goal graph, a durable board that outlives any one session.
goal_advanceAdvance a node's status; a leaf moving to done requires evidence.
goal_frontierThe ready frontier: nodes whose blocking dependencies are all done.
goal_listList goal-graph nodes filtered by lane, status or kind.
goal_sync_relayCarry one request for the local task-board sync engine when it runs in relay mode.
ctx_workspace_listList the workspaces this credential can write to.
ctx_workspace_ensureGet or create a workspace, idempotently.
ctx_project_ensureGet or create a project inside a workspace, idempotently.

Next steps

  • Read the full documentation for detailed tool parameters and API reference.
  • Explore the REST API for programmatic access outside of MCP.
  • Invite team members from the dashboard to share context across your organization.