Common Ninja MCP Server

The Common Ninja MCP server lets AI assistants and agents — Claude, ChatGPT, Cursor, and any Model Context Protocol client — create, update, and manage your Common Ninja widgets in plain language.

It is hosted and ready to use at:

https://mcp.commoninja.com/mcp

Which connection method should I use?

Method	Best for	Auth	Setup
Connect (OAuth)	Most users. One URL, log in once.	Browser login to Common Ninja	None — add the URL
API token (hosted)	Clients without OAuth, scripts, CI	Account API token	Paste URL + token
Local (stdio)	Self-hosting / offline / development	Account API token	Clone, build, configure

tip

Start with Connect (OAuth) — there is nothing to copy or paste beyond the URL.

---

Option A — Connect with OAuth (recommended)

Add the MCP server as a custom connector using only the URL. Your client opens a Common Ninja login + consent screen, and you're connected — no token to manage.

URL: https://mcp.commoninja.com/mcp

Claude (Desktop & Web)

1. Settings → Connectors → Add custom connector.
2. Paste https://mcp.commoninja.com/mcp and click Add / Connect.
3. Log into Common Ninja and approve access.

ChatGPT

1. Settings → Connectors → Add (custom / MCP).
2. Paste https://mcp.commoninja.com/mcp and connect.
3. Log into Common Ninja and approve access.

Cursor

Add an HTTP MCP server pointing at the URL (Cursor will run the OAuth login):

{
  "mcpServers": {
    "commonninja": {
      "url": "https://mcp.commoninja.com/mcp"
    }
  }
}

Claude Code (CLI)

claude mcp add --transport http commonninja https://mcp.commoninja.com/mcp

Claude Code opens the browser login on first use.

note

Custom connectors with OAuth are available on paid plans of Claude and ChatGPT. If your client doesn't support custom connectors, use Option B below.

---

Option B — Connect with an API token (manual config)

For clients without OAuth, or for scripts and CI, authenticate with your Account API token instead of logging in.

Get your token: Common Ninja dashboard → Account → API key.

You can pass the token two ways:

1. In a header (recommended):

claude mcp add --transport http commonninja https://mcp.commoninja.com/mcp \
  --header "CN-API-Token: YOUR_API_TOKEN"

2. In the URL path:

https://mcp.commoninja.com/mcp/YOUR_API_TOKEN

Generic client config (any MCP client that supports HTTP transport):

{
  "mcpServers": {
    "commonninja": {
      "url": "https://mcp.commoninja.com/mcp",
      "headers": { "CN-API-Token": "YOUR_API_TOKEN" }
    }
  }
}

caution

A token in the URL path can appear in proxy/access logs. Prefer the CN-API-Token header, and rotate your token from the dashboard if it's ever exposed.

---

Option C — Run locally (stdio)

Run the server on your own machine for development, offline use, or self-hosting. Uses the stdio transport with desktop MCP clients.

Prerequisites: Node.js v20+, npm or yarn, and an Account API token.

git clone https://github.com/CommonNinja/commonninja-mcp-server.git
cd commonninja-mcp-server
npm install
npm run build

Configure your client (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "commonninja": {
      "command": "node",
      "args": ["/path/to/commonninja-mcp-server/build/index.js"],
      "env": {
        "COMMONNINJA_ACCOUNT_ACCESS_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

---

Verify the connection

After connecting, ask your assistant something like:

List my Common Ninja widgets.

or

Create an FAQ widget with three questions about shipping and add it to my store.

Health check: GET https://mcp.commoninja.com/healthz returns server status.

---

Available tools

Widgets

• commonninja_get_widget — Get a widget's data by ID
• commonninja_get_widget_schema — Get the JSON schema for a widget type
• commonninja_get_widget_with_schema — Get a widget's data and its type schema in one call (use before updating)
• commonninja_get_widget_integrations — Read a widget's integration config (integrations, notifications, email, payments) — read-only
• commonninja_create_widget — Create a widget of a given type
• commonninja_update_widget — Merge new data into an existing widget
• commonninja_validate_json_schema — Validate widget data against a schema
• commonninja_delete_widget — Delete a widget by ID
• commonninja_list_widgets — List widgets (paginated)
• commonninja_get_widget_types — List all available widget types
• commonninja_get_widget_editor_url — Get the editor URL for a widget
• commonninja_get_widget_embed_code — Get the embed code for a widget

Projects

• commonninja_list_projects — List projects (paginated)
• commonninja_get_project — Get project details by ID

CRM (read-only)

• commonninja_project_list_contacts — List a project's contacts
• commonninja_project_get_contact — Get a contact by ID
• commonninja_project_list_submissions — List a project's form submissions
• commonninja_project_get_submission — Get a submission by ID

Analytics

• commonninja_get_widget_analytics — Get analytics for a widget

Utility

• commonninja_links — Get common Common Ninja platform links

---

Notes

• Transport: the hosted server uses streamable HTTP (POST to /mcp). GET/DELETE are not used.
• Multi-tenant & stateless: each request is scoped to the credentials it carries — your data is only ever accessed with your own login or token.
• Source & updates: Common Ninja MCP Server on GitHub.