Use NOCK with AI Agents

AI agents can use NOCK as a focused ticket system when they need to create work, summarize customer feedback, or update workflow state. The safest setup is a project-scoped API key with the minimum scopes needed for the agent's job.

Recommended agent contract

Do not give an agent a workspace-wide key unless it needs access to every project.

Use the nock-mcp skill for MCP ticket work

Use the optional nock-mcp skill from the public plugin repository when a Codex, Claude Code, or other Agent-Skills-compatible coding agent will read or change NOCK tickets through MCP. It adds the repeatable safety workflow for untrusted ticket content, read-before-write, retries, and explicit approval for customer-visible replies. The MCP server instructions remain the fallback when the skill is not installed.

The skill does not connect the server or hold credentials. Configure OAuth for interactive agents or a scoped Agent Key for headless agents through MCP Server, then install the public skill in the agent's supported project discovery location.

Stable workflow

1. Read available projects with GET /api/v1/projects.
2. Create tickets with POST /api/v1/tickets.
3. Store returned ticket IDs in the agent's own memory or database.
4. Read ticket details before making updates.
5. Update only fields the agent is responsible for.
6. Use customer-visible replies only when the message should be visible outside the team.

What agents should not assume

• Linear may not be connected.
• GitHub Issues and Jira are external adapter patterns today, not native NOCK features.
• Dashboard AI triage is an internal operator workflow, not a Public API endpoint.
• Internal notes are not exposed through the Public API.
• Webhook delivery can be duplicated; downstream agents must be idempotent.
• File upload and image upload are not part of the Public API yet.

Choose the integration layer

The plugin and standalone skill use the same canonical source; installing both does not add capabilities. Neither contains credentials, grants scopes, or replaces server-side authorization.

The public plugin source is tomkloevekorn/nock-agent-plugin. It connects to the hosted endpoint at https://nocknock.cloud/mcp. Claude Code and Codex can install that Git repository as a source. For Cursor, the standalone MCP configuration is supported; loading plugins/nock as a local plugin remains experimental. For the exact native plugin commands—or the smaller direct MCP setup—follow MCP Server. That page is the source of truth for authentication and current directory availability.

NOCK has not been submitted to the public Cursor, Claude, or OpenAI plugin directories. The public Git source does not make it searchable by name in those directories, but users can give an agent the official MCP guide URL and let it perform the supported direct or Git-based setup.

Prompt guidance

When giving NOCK access to an agent, include this operational policy:

You are working with NOCK tickets.
Use NOCK as the source of truth.
Never expose internal notes to customers.
Before updating a ticket, read the ticket detail.
Use customer-visible replies only for messages intended for the customer.
Use idempotency for webhook events based on x-nock-delivery or payload id.
Do not assume AI triage has run unless a human operator tells you to use that result.

Machine-readable docs

The docs app exposes llms.txt, llms-full.txt, and /openapi.yaml so agents can ingest the public documentation and machine-readable API contract. When an agent needs GitHub Issues, Jira, or another third-party tool, point it at External Adapters so it uses the API/webhook contract rather than assuming a native adapter exists.

Use MCP Server for Codex, Claude Code, and HTTP MCP clients. Use API Keys when you need to create a project-scoped credential for a custom agent or automation.

Dashboard-only AI triage is documented separately at AI Ticket Triage.