Ship analytics plans with confidence.

Build with Notiqo

Notiqo keeps your product analytics plan connected to the code you ship. The MCP lets Claude Code and Codex review and import a canonical guide, while the CLI scans repositories and exports deterministic tracking plans.

• Every import starts with a dry-run.
• Writes are explicit, idempotent, and scoped to one project.
• The CLI can print Markdown, JSON, or a guide ready for import.

Create a token

In the Notiqo dashboard, open Integrate → CLI token → Create CLI token. The token is shown once, expires after 90 days, and is limited to one project. The dialog also shows the login command with your project ID filled in.

Run it in any terminal and paste the token when asked. Input is hidden, the token is checked against Notiqo before anything is saved, and it is stored in ~/.notiqo/credentials.json, readable only by you. Both the MCP server and the notiqo CLI use it.

npx -y @notiqo/mcp login your-project-id

There is no need to restart Claude Code or Codex: the server reads the saved token on every call, so just retry your request. To remove it, run npx -y @notiqo/mcp logout your-project-id.

Connect the MCP server

Install the published server with npx. The configuration needs no token: the server uses the one saved by login, and the project ID from .notiqo/config.json (created by npx -y @notiqo/mcp init your-project-id).

{
  "mcpServers": {
    "notiqo": {
      "command": "npx",
      "args": ["-y", "@notiqo/mcp"]
    }
  }
}

[mcp_servers.notiqo]
command = "npx"
args = ["-y", "@notiqo/mcp"]

A NOTIQO_TOKEN environment variable still works and takes precedence over the saved token, which is useful in CI. An empty value or a literal ${NOTIQO_TOKEN} is ignored.

Use notiqo_import_guide with dryRun: true first. Ask for explicit confirmation before applying changes; draft events retain code provenance and repeated imports remain safe.

Use the CLI

Scan a repository with the notiqo command. The default output is designed for review; add --push only when you are ready to send the guide to a project. The CLI uses --token, then NOTIQO_TOKEN, then the token saved by login.

npx notiqo scan --format guide --project your-project-id
npx notiqo scan --format guide --push --project your-project-id
npx notiqo scan --format json --only-existing

MCP example

Ask your agent to import a guide in two deliberate steps: preview the changes first, then apply the exact result you approved.

{
  "guide": "docs/tracking-guide.json",
  "projectId": "your-project-id",
  "dryRun": true
}

Review the proposed events, parameters, and warnings returned by the dry-run. When the plan is correct, repeat the same request with dryRun: false and confirm the write.

Agent: Import docs/tracking-guide.json for project your-project-id with dryRun=true.

Agent: The dry-run found 3 new events and 1 warning. Apply these changes?

You: Yes, apply the reviewed changes.

Agent: Import completed. 3 events created; source: code.

Run it in CI

In CI there is no saved login, so use NOTIQO_TOKEN as a pipeline secret. JSON output is machine-readable and the scan exits with code 1 when issues are found.

- name: Scan tracking plan
  run: npx notiqo scan --push --json --project ${{ vars.NOTIQO_PROJECT_ID }}
  env:
    NOTIQO_TOKEN: ${{ secrets.NOTIQO_TOKEN }}

Guide contract

Guides use the canonical JSON schema shipped with @notiqo/mcp. Keep the Markdown guide and JSON representation together, and include generatedBy metadata when producing a guide in automation.

{
  "generatedBy": "notiqo",
  "schemaVersion": "1",
  "project": { "name": "Checkout" },
  "events": []
}

Security and troubleshooting

• A missing token error tells you the exact login command to run; no restart is needed afterwards.
• 401 explains why the token was rejected: unknown or incomplete, revoked, expired, malformed, or a literal ${NOTIQO_TOKEN} placeholder. Create a new token and run login again.
• 403 means the user is not a member of the project or lacks the required role.
• The MCP receives guide data, not your repository source code.
• Rotate tokens regularly. Keep them in the login store locally and in secrets in CI, never in Git.