Notra MCP Server

An MCP (Model Context Protocol) server for the Notra API. It manages posts, brand identities, integrations, schedules, GEO visibility scans, competitors, content briefs, and AI traffic analytics.

Setup

You can generate an API key from your Notra workspace dashboard under Developer > API Keys.

Node.js 20 or newer is required.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "notra": {
      "command": "npx",
      "args": ["-y", "@usenotra/mcp"],
      "env": {
        "NOTRA_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add notra -- npx -y @usenotra/mcp

Then set the NOTRA_API_KEY environment variable in your shell before launching Claude Code.

Codex

export NOTRA_API_KEY=your-api-key
codex mcp add notra --env NOTRA_API_KEY="$NOTRA_API_KEY" -- npx -y @usenotra/mcp

Run codex mcp list to verify the connection. The Codex CLI, desktop app, and IDE extension share this MCP configuration.

OpenCode

Set NOTRA_API_KEY in your shell, then add the server to your project-level opencode.json or the global ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "notra": {
      "type": "local",
      "command": ["npx", "-y", "@usenotra/mcp"],
      "enabled": true,
      "environment": {
        "NOTRA_API_KEY": "{env:NOTRA_API_KEY}"
      }
    }
  }
}

Amp

Run amp config edit and add the following to your settings, or place it in .amp/settings.json for a workspace-specific configuration:

{
  "amp.mcpServers": {
    "notra": {
      "command": "npx",
      "args": ["-y", "@usenotra/mcp"],
      "env": {
        "NOTRA_API_KEY": "${NOTRA_API_KEY}"
      }
    }
  }
}

Set NOTRA_API_KEY in the environment before launching Amp. Workspace MCP servers may require approval with amp mcp approve notra.

Remote MCP (OAuth)

The hosted streamable HTTP server at https://mcp.usenotra.com/mcp uses OAuth as the primary authentication method. It supports the current 2026-07-28 MCP protocol as well as legacy 2025 clients. MCP clients should discover protected resource metadata at:

https://mcp.usenotra.com/.well-known/oauth-protected-resource

That metadata points to the Notra authorization server (WorkOS AuthKit) at https://oauth.usenotra.com, which supports dynamic client registration (RFC 7591). The MCP server also mirrors the authorization server metadata at https://mcp.usenotra.com/.well-known/oauth-authorization-server.

API key alternative

Remote connections also accept a Notra API key as a static Authorization: Bearer … header. Generate one from your Notra workspace dashboard under Developer > API Keys. OAuth-capable clients should prefer the OAuth flow instead of manual key configuration.

For self-hosted HTTP deployments, OAuth validation can be configured with:

WORKOS_AUTHKIT_DOMAIN=oauth.usenotra.com
WORKOS_CLIENT_ID=client_xxx
NOTRA_MCP_RESOURCE=https://mcp.usenotra.com

The issuer is https://{WORKOS_AUTHKIT_DOMAIN} and must match the iss claim in tokens minted by AuthKit; a mismatch causes every bearer token to be rejected. Token signatures are verified against https://{WORKOS_AUTHKIT_DOMAIN}/oauth2/jwks.

When NODE_ENV=development, the default AuthKit domain is essential-berry-67-development-2.authkit.app; production defaults to oauth.usenotra.com. auth.usenotra.com is the WorkOS Authentication API domain and serves none of the OAuth endpoints, so it does not work here.

Legacy 2025 sessions expire after 30 minutes of inactivity. Each OAuth user or API key can hold NOTRA_MCP_MAX_SESSIONS_PER_PRINCIPAL sessions (default 50); beyond that, its own least recently used session closes. When the server holds NOTRA_MCP_MAX_SESSIONS sessions (default 1000), new sessions are rejected with HTTP 503 and Retry-After instead of closing other users' sessions.

Toolsets

All 97 tools are exposed by default, which costs roughly 20k tokens of agent context. To load only what you need, pick toolsets with NOTRA_MCP_TOOLSETS (stdio and HTTP) or the toolsets query parameter on the remote endpoint:

Workspace tools and submit_feedback are always available.

NOTRA_MCP_TOOLSETS=content npx -y @usenotra/mcp

https://mcp.usenotra.com/mcp?toolsets=geo

Tools

Workspace

Each MCP connection operates in the workspace bound to its bearer token. To act in another workspace, authorize a separate connection for that workspace; list_workspaces discovers access but does not switch credentials.

Posts

Brand Identities

Integrations

Schedules

Event Triggers

Chats

Skills

Projects

GEO features are scoped to a project. Most GEO tools take a projectId; call list_projects first to find it. GEO tools require an organization-scoped API key and the GEO plan.

GEO settings

GEO prompts and sequences

GEO competitors

GEO scans and visibility

GEO content briefs

Agent readiness

AI traffic

Feedback

Development

Use Node 22.12+ (Node 22) or Node 24 and the pnpm version pinned in package.json:

corepack enable
pnpm install --frozen-lockfile
pnpm test
pnpm run test:coverage
pnpm run typecheck
pnpm run format:check

Tool output schemas in src/schemas/api-responses.ts are generated from the Notra OpenAPI spec. Run pnpm run generate:output-schemas after the API changes; CI fails when the file is stale.

Vitest runs directly against the source with Zod compilation enabled. CI runs tests, typechecking, formatting checks, and the build on pull requests and pushes to main.