Skip to main content

Quickstart: AI Agents

Connect your AI coding agent to appgrammar. You can start immediately without an account, or use an MCP token for a persistent setup.

Option A: No Account Required​

AI agents can start using appgrammar immediately — no human account or pre-authorization needed. Provision a session, build freely, and hand off the work to a human via a claim link.

1. Provision a Session​

curl -X POST https://appgrammar.com/api/agent/sessions \
  -H "Content-Type: application/json" \
  -d '{"label": "Building a task management app"}'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "claim_code": "CL-a8f3b2",
    "claim_url": "https://appgrammar.com/claim/CL-a8f3b2",
    "expires_at": "2026-04-03T12:00:00.000Z"
  }
}

2. Use the Token​

The token works as a standard bearer token. Configure it in your MCP client:

{
  "mcpServers": {
    "appgrammar": {
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOi..."
      }
    }
  }
}

All 30+ tools are available with the agent session token.

3. Save Credentials​

Save the token and claim details so they survive if the conversation ends:

<!-- .appgrammar-session.md -->

# Appgrammar Agent Session

- **Token:** `eyJhbGciOi...`
- **Claim URL:** https://appgrammar.com/claim/CL-a8f3b2
- **Claim Code:** CL-a8f3b2
- **Expires:** 2026-04-03T12:00:00.000Z

> Visit the claim URL to take ownership of everything built in this session.
tip

Add .appgrammar-session.md to .gitignore so the bearer token is not accidentally committed.

4. Hand Off to the Human​

When done, show the claim URL. The human visits the link, signs in, and takes atomic ownership of everything the agent built — appgrammars, architectures, collections, and tokens all transfer in one transaction.

Limits: 30-day session TTL, max 20 appgrammars per session, low-volume rate limiting on session creation (per IP). Requests beyond the allowed rate return 429.

Option B: MCP Token (Persistent)​

For a persistent setup, sign in at appgrammar.com and go to MCP & Hooks in the sidebar.

1. Generate a Token​

Click Generate Token, give it a name, and copy it.

2. Configure Your Agent​

Claude Code​

{
  "mcpServers": {
    "appgrammar": {
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Cursor / VS Code / Windsurf​

Add to .cursor/mcp.json (Cursor), VS Code MCP settings, or Windsurf config:

{
  "mcpServers": {
    "appgrammar": {
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Codex / Antigravity​

Same JSON format — add to your tool's MCP configuration file.

The MCP & Hooks page generates ready-to-paste snippets for all 6 supported IDEs/CLIs.

3. Team Connections (Optional)​

If you're part of a team, add a team-scoped connection so your team's conventions are automatically applied:

claude mcp add --transport http appgrammar-myteam https://appgrammar.com/mcp \
  --header "Authorization: Bearer YOUR_MCP_TOKEN" \
  --header "X-Team-Id: YOUR_TEAM_UUID"

For Cursor/VS Code, add "X-Team-Id": "YOUR_TEAM_UUID" to the headers object.

Create and Execute​

Tell your agent:

Create an appgrammar for a task management API with TypeScript and PostgreSQL, then execute it.

Your agent will:

  1. Call appgrammar_create to start the 5-step creation pipeline
  2. Submit each step result via appgrammar_create_submit
  3. Call appgrammar_start to get the first execution stage
  4. Work through each stage via appgrammar_next until dn: true

What Happens During Creation​

StepOutput
1. ArchitectureModule graph, dependencies, technology choices
2. Design SystemUI framework, colors, typography, component patterns
3. Task DAGOrdered build steps with parallel groups
4. File RegistryEvery file path with exports and dependencies
5. EnrichmentCompressed specifications for each step

What Happens During Execution​

Each call to appgrammar_next returns a stage containing one or more parallel groups. Groups within a stage can run concurrently. Steps within a group run sequentially.

Stage 0: [Group A: step 1, step 2] [Group B: step 1]
Stage 1: [Group C: step 1, step 2, step 3]
Stage 2: [Group D: step 1]

Each step includes file paths, compressed specification, context from previous steps, and a registry of all project files.

Keeping the Blueprint in Sync​

After execution, as you iterate on your codebase — adding features, fixing bugs, refactoring — the appgrammar drifts from reality. Two mechanisms close this feedback loop:

appgrammar_update​

The update tool syncs the blueprint with your current codebase:

Run appgrammar_update to sync the blueprint with the current codebase.

The agent compares the codebase against the blueprint, identifies structural changes (modules added, removed, or updated), and submits a structured changeset. If you own the appgrammar, the update is applied in place with an automatic version snapshot. Otherwise, a fork is created.

This is a multi-turn operation: the first call returns the full appgrammar state, the agent analyzes the diff, then submits changes via appgrammar_tool_submit.

Auto-Sync Hooks (Claude Code)​

Add a hook to .claude/hooks.json in your project to get soft reminders when files are modified:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo \"If this was a significant change, consider running appgrammar_update to sync the blueprint. Check appgrammar.md for the ID.\""
      }
    ]
  }
}

This is a soft reminder, not a hard block. The agent sees the message after each file write or edit and decides whether syncing is appropriate. The MCP & Hooks page generates this configuration for you.

For other IDEs/CLIs, the agent uses the appgrammar.md file in your project root to know when to sync.

Next Steps​