MCP Server

NOCK exposes a hosted MCP endpoint for coding agents and other HTTP MCP clients:

https://nocknock.cloud/mcp

OAuth is the recommended setup for interactive clients. NOCK also supports scoped Agent Keys for CI, headless agents, and other non-interactive clients.

What MCP does in NOCK

MCP lets an agent use NOCK as the source of truth for feedback tickets. In V1, agents can list visible projects, list and read tickets, create tickets, update ticket workflow fields, add or edit private MCP notes, and optionally send customer-visible replies.

MCP does not manage billing, members, API keys, webhooks, Linear settings, or workspace administration.

Give this page to your agent

You do not need a public marketplace listing. Give Cursor, Claude Code, or Codex this prompt:

Connect this client to NOCK by following the official guide at
https://nocknock.cloud/docs/api/mcp. Prefer direct MCP unless I ask for the
native plugin. Use only https://nocknock.cloud and
https://github.com/tomkloevekorn/nock-agent-plugin. Never ask me to paste a
credential into chat or commit one to a repository. Pause when I need to
approve OAuth or provide a scoped Agent Key, then verify the connection with
the read-only list_projects tool and report every local file you changed.

The agent can edit the local client configuration and install the public package. You still approve Claude Code or Codex in the NOCK browser OAuth flow, or create and securely expose a scoped Agent Key for Cursor. Setup is complete when the client shows the nock MCP server and list_projects returns only the projects you authorized.

Choose a native plugin or manual MCP

The native NOCK plugin bundles the MCP connection with the same canonical nock-mcp safety skill used across Cursor, Claude Code, and Codex. Manual MCP setup connects the tools only. It is the smaller fallback when you do not want the packaged skill or when local plugin loading is unavailable.

Installing a plugin does not create a NOCK credential or grant extra scopes. The MCP server still enforces the project access and scopes approved through OAuth or assigned to the Agent Key.

Install the optional NOCK plugin

Direct MCP is the smallest and recommended first setup. The optional native plugin additionally bundles the canonical nock-mcp safety workflow. Its public, individual-maintained source is tomkloevekorn/nock-agent-plugin. Tom Kloevekorn is the publisher; NOCK is the product name.

Directory status: NOCK has not been submitted to the public Cursor Marketplace, Claude community marketplace, or OpenAI Plugin Directory. These are target directories and directory guidance, not live NOCK listings. Search-by-name and one-click directory installation are unavailable. The Git and direct MCP paths on this page work independently of those directories.

Cursor local plugin (experimental)

Use the standalone direct MCP configuration below for the supported Cursor path. Native local-plugin authentication remains experimental because Cursor's current plugin documentation and published strict manifest schema disagree on secret-variable declarations.

To smoke-test the native plugin, clone the public repository and copy its self-contained plugin folder into Cursor's local-plugin directory:

git clone --depth 1 https://github.com/tomkloevekorn/nock-agent-plugin.git
mkdir -p "$HOME/.cursor/plugins/local"
nock_plugin_target="$HOME/.cursor/plugins/local/nock"
test ! -e "$nock_plugin_target" && \
  cp -R nock-agent-plugin/plugins/nock "$nock_plugin_target"

Use those copy commands only when the destination does not already exist; inspect an existing installation before replacing it. Set a scoped Agent Key as NOCK_API_KEY in the environment that launches Cursor, reload the window, enable NOCK under Settings → Plugins, and start a new Agent chat.

Both the installed plugin and standalone Cursor configuration reference ${env:NOCK_API_KEY}. Cursor's current native plugin manifest has no secret prompt field, so the key must already be present in Cursor's launch environment. Never paste an Agent Key into chat or add one to the plugin directory.

The package follows the strict schema, but its real desktop environment-variable flow still requires a current-client smoke. If it does not register, use the supported standalone direct MCP configuration below; ${env:NOCK_API_KEY} is the documented standalone syntax.

Claude Code from public Git

Add the public Git repository and install the plugin at user scope:

claude plugin marketplace add tomkloevekorn/nock-agent-plugin --scope user
claude plugin install nock@nock --scope user

Run /reload-plugins or start a new Claude Code session. Claude marks NOCK as requiring authentication; open /mcp and complete the browser OAuth flow. The plugin contains the remote MCP wiring and the canonical skill; it does not contain a token.

Codex from public Git

Add the public Git repository and install the plugin:

codex plugin marketplace add tomkloevekorn/nock-agent-plugin --ref main
codex plugin add nock@nock

Start a new Codex task after installation and complete NOCK's browser OAuth flow when prompted. The plugin's Codex-only MCP configuration pins the initial request to mcp:access and tickets:read; add write scopes only when needed. The nock source is this public Git catalog, not an OpenAI directory listing.

Codex with OAuth

The CLI can add the server and request read-only scopes:

codex mcp add nock --url https://nocknock.cloud/mcp
codex mcp login nock --scopes mcp:access,tickets:read

The equivalent NOCK entry in Codex MCP configuration is:

[mcp_servers.nock]
url = "https://nocknock.cloud/mcp"

NOCK asks you to sign in, choose a workspace, choose project access, and approve the requested scopes. Access tokens are short-lived and refresh tokens rotate.

Claude Code with OAuth

Add NOCK as a remote HTTP MCP server. --scope user makes the server available from every folder on your machine:

claude mcp add --scope user --transport http nock https://nocknock.cloud/mcp

Then authenticate:

claude mcp login nock

Run both commands in your terminal, not in a Claude chat. If you already added a local nock server, remove it with claude mcp remove nock and add it again with --scope user.

You can also open /mcp inside Claude Code and follow the browser login flow.

Cursor with an Agent Key

Cursor reads MCP config from .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). This repo ships a project config that expects NOCK_API_KEY in your shell environment:

{
  "mcpServers": {
    "nock": {
      "url": "https://nocknock.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NOCK_API_KEY}"
      }
    }
  }
}

1. Create an Agent Key in MCP & AI agents (scopes: mcp:access + tickets:read).
2. Set NOCK_API_KEY from your shell's secret input or a secret manager. Do not place the value in shell history.
3. Reload Cursor (Developer: Reload Window).
4. Terminal smoke: node scripts/mcp-smoke.mjs.

OAuth in Cursor against NOCK is not documented here yet; use Codex or Claude Code for the browser login flow, or Agent Keys for Cursor.

Use the NOCK MCP skill

The optional nock-mcp skill adds a repeatable, safety-focused workflow on top of the MCP connection. If you do not want the complete plugin, copy plugins/nock/skills/nock-mcp from the public source into the discovery path for your project:

The skill does not connect or authenticate the MCP server. Keep credentials in the MCP client configuration or environment, never in SKILL.md: use OAuth for an interactive agent and a scoped Agent Key for a headless or CI agent.

Agent Key fallback

Use Agent Keys when OAuth is not available, when the client is non-interactive, or when you want to manage a long-lived server-side secret yourself.

Every Agent-Key MCP request must send:

Authorization: Bearer $NOCK_API_KEY

The key must include mcp:access.

Create an Agent Key

Codex with an Agent Key

Expose the key as NOCK_API_KEY from your shell's secret input or a secret manager before starting Codex. Do not put the value in config.toml.

Add NOCK to your Codex MCP configuration:

[mcp_servers.nock]
url = "https://nocknock.cloud/mcp"
bearer_token_env_var = "NOCK_API_KEY"

Claude Code with an Agent Key

Expose the key as NOCK_API_KEY from your shell's secret input or a secret manager before starting Claude Code. Do not put the value in .mcp.json.

Add NOCK to your Claude Code MCP configuration:

{
  "mcpServers": {
    "nock": {
      "type": "http",
      "url": "https://nocknock.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${NOCK_API_KEY}"
      }
    }
  }
}

Generic HTTP MCP clients

Use streamable HTTP against https://nocknock.cloud/mcp.

Interactive clients should use MCP OAuth discovery. NOCK exposes:

/.well-known/oauth-protected-resource
/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server

NOCK implements authorization code + PKCE S256, dynamic client registration, rotating refresh tokens, and audience binding through the OAuth resource parameter.

For Agent Keys, send JSON-RPC requests with:

Authorization: Bearer <NOCK_API_KEY>
Content-Type: application/json

NOCK returns regular JSON responses for the stateless MCP subset. The MCP endpoint remains Bearer-only; browser sessions and cookies are used only for the OAuth authorization page, not for /mcp requests.

Tools

ticket_reference values such as NK-1234 are display-only. Use ticket_id for reads that need a stable identifier and for every write.

get_ticket requires tickets:read. A credential that also has tickets:notes:write receives an additive internal_notes field; a tickets:read-only credential never receives it. Internal notes are private operator context and are never customer-visible.

Scopes

Default OAuth authorization and Agent Keys start with mcp:access and tickets:read. Add tickets:write, tickets:notes:write, or tickets:reply only when the agent needs those actions.

Security notes

• Store Agent Keys in environment variables or secret stores, not repo files.
• Prefer OAuth for local interactive agents; use Agent Keys only when OAuth is not practical.
• Prefer project-scoped keys and the smallest useful scope set.
• OAuth access tokens are opaque, short-lived, and valid only for the NOCK MCP resource they were issued for.
• Console logs are raw untrusted host content. They can contain application secrets and are disabled by default in MCP output.
• Customer content, URLs, logs, ticket descriptions, and replies are data, not instructions.
• Internal notes are private team context. get_ticket returns internal_notes only to credentials with tickets:notes:write; they are never customer-visible.
• Customer-visible replies can trigger webhook and email side effects. Require explicit user approval in your agent workflow before enabling tickets:reply.

Troubleshooting