CogniForgeCogniForgeOn-Prem Ready
Documentation · Guide

Use your IDE's AI with CogniForge

If you already pay for an agent IDE — Claude Code, Cursor, GitHub Copilot, or Google Antigravity — it can become a first-class CogniForge implementation seat: implementing tickets and authoring project documents on your own subscription, while CogniForge stays the source of truth (plan, tickets, branches), the gatekeeper (validation, approval gates), and the auditor (ledger, versions). This is a different, complementary feature from using your Claude subscription on a build VM — that one powers CogniForge's own automated pipeline; this one lets your IDE's agent drive the work itself, interactively, from your own machine.

How this works, in one sentence: CogniForge exposes a single hosted endpoint (/mcp) that speaks MCP (Model Context Protocol) — your IDE connects to it once with a token, and gets tools like list_tickets, start_ticket, validate_ticket, and get_document_task. No install — nothing runs locally except your IDE's own agent.

1Fastest path: the VS Code extension

If you're on VS Code, the extension automates everything below AND adds one more thing: the platform can push tickets straight into your open workspace and start a headless Claude Code session for you (the "auto-deliver to my own IDE" delivery mode).

  1. Go to your account's API keys page (avatar menu → API keys) and create one. This is self-service and user-scoped — unlike the tenant integration tokens in step 2 below, any user can mint their own without a tenant admin.
  2. Download the extension from Admin → IDE integrations and install the .vsix (Extensions panel → … → Install from VSIX…).
  3. Open the CogniForge icon in the activity bar, enter your platform URL and API key, click Connect.
  4. Click Connect Claude ↔ Platform — runs claude mcp add for you, so you can skip straight to step 4 below (the work-queue loop) instead of copying a command by hand.
Needs the Claude Code CLI on whichever machine runs VS Code's extension host (the remote host, over Remote-SSH) — install with curl -fsSL https://claude.ai/install.sh | bash. Having the Claude Code VS Code extension installed and logged in is a separate thing and doesn't put the CLI on PATH by itself.

2The manual way: any MCP client

Cursor, Copilot, Antigravity, or Claude Code without our extension — connect straight to the hosted MCP endpoint with a tenant-scoped integration token instead:

  1. Go to Admin → IDE integrations.
  2. Click New integration token, give it a name (e.g. "my-laptop"), and choose a scope:
    • Read — browse projects, tickets, and documents only.
    • Write — also implement/validate/complete tickets and submit/approve documents. This is what most developers want.
  3. Copy the connect command it shows you — this is the only time the token is shown.

3Connect your IDE

The token page gives you a ready-to-run command. For Claude Code, it looks like this (yours will have a real URL and token already filled in):

claude mcp add --transport http cogniforge "https://your-cogniforge-host/mcp/" --header "Authorization: Bearer <your-token>"

Cursor, Copilot, and Antigravity all support the same idea — an HTTP MCP server with a bearer-token header — check your client's MCP settings for the equivalent one-liner or config entry.

There's nothing to install and nothing running locally besides your IDE's own agent — the MCP server is hosted by CogniForge itself.

4Try it: the work-queue loop

Ask your IDE's agent to call the get_work_instructions tool (or, in Claude Code, run the work-queue prompt) — it returns the whole loop:

  1. list_tickets(status="To Do") — pick the first unblocked ticket.
  2. start_ticket(key) — gates check (same rules the platform's own dispatch uses), then returns the milestone branch to check out.
  3. Implement per the ticket's scope/acceptance criteria — use get_document(project, kind) for the approved SAD's contracts, and get_context_package for ranked, relevant code instead of blind local search.
  4. Run the commands from get_testing_bar(project) locally first.
  5. Push your branch, then call validate_ticket(key) — this runs the platform's real test gate against your pushed branch head. On failure, fix and push again, then re-validate.
  6. complete_ticket(key) — only allowed once validation has passed for your CURRENT branch head.
If you're on the VS Code extension's auto-deliver push channel, one more session type can show up in your workspace besides regular tickets: the milestone technical-debt review (see the auto-deliver guide), dispatched right after you click Approve on a milestone whose PR just merged. It runs through the exact same connected session as your ticket work, just with a different job — reviewing the merged code instead of implementing a ticket.

5Author documents the same way

For a new greenfield project (or any missing document), the pattern is "serve the recipe, accept the dish":

  1. get_document_task(project) — returns the next needed document's fully assembled prompt (every prior approved document's context already substituted in).
  2. Author the document yourself, using your IDE's own model.
  3. submit_document(project, kind, content) — stores it as a draft through the same guards the platform's own generation uses.
  4. approve_document(project, kind) — advances the project to its next stage.

Revising an existing document works the same way via get_refine_task (current content + your feedback) and the same submit_document call.

If something doesn't work

  • 401 / "Invalid or revoked token" — the token or API key was revoked, or you pasted it wrong. Mint a new one from Admin → IDE integrations (tenant token) or your account's API keys page (personal key).
  • A write tool isn't listed / "requires a write-scope token" — your token is read-only. Mint a new write-scope token.
  • Extension sidebar stuck on "Connecting…" forever, no error logged — usually means the machine actually running the extension (the Remote-SSH host, if you use one — check the VS Code status bar) can't reach your platform's domain at all. Open a terminal there and try curl -v https://your-platform-host/mcp/ — if that hangs too, it's a network/DNS/firewall issue on that machine, not the extension.
  • "Connect Claude ↔ Platform" fails with "spawn claude ENOENT" — the Claude Code CLI isn't installed (or not on PATH) on the machine running the extension host. See the install command in step 1.
  • validate_ticket keeps failing — the error message is the same distilled test output the platform's own pipeline shows; fix the actual cause and push again.
  • complete_ticket says the branch isn't validated — you pushed again after your last validate_ticket call. Run validate_ticket again against the new branch head.
Use your IDE's AI with CogniForge — CogniForge Docs