Notra README

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.

Account API keys

An account API key belongs to you rather than one workspace, so it works in every workspace you're a member of. If you belong to more than one, choose the workspace this server acts on with NOTRA_ORGANIZATION_ID:

{
  "env": {
    "NOTRA_API_KEY": "your-account-api-key",
    "NOTRA_ORGANIZATION_ID": "your-workspace-id"
  }
}

Without it, tools fail with a message asking you to pick a workspace. list_workspaces works without a selection and shows the ids. Organization API keys ignore NOTRA_ORGANIZATION_ID.

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.

Workspace-scoped URL

Add a workspace id or slug to the URL to pin a connection to one workspace: https://mcp.usenotra.com/mcp/<workspace>. This is the way to pick a workspace in clients that only accept a URL and can't send custom headers.

• Claude: Settings > Connectors > Add custom connector, URL https://mcp.usenotra.com/mcp/acme

• Claude Code: claude mcp add --transport http notra https://mcp.usenotra.com/mcp/acme

• Cursor (~/.cursor/mcp.json):

  config.jsonCopy

  {
    "mcpServers": {
      "notra": { "url": "https://mcp.usenotra.com/mcp/acme" }
    }
  }
  

On a scoped URL:

• API keys act in that workspace. The URL wins over an X-Notra-Organization-Id header. An organization key only works on its own workspace's URL; any other workspace is rejected with HTTP 403 by the Notra API.
• OAuth works the same as on /mcp, but the workspace you authorize must be the one in the URL. Otherwise requests are rejected with HTTP 403 instead of silently acting on another workspace. The OAuth challenge announces the same resource as /mcp, so clients get a normal Notra token; the workspace in the URL is enforced through the workspace you authorize.
• list_workspaces is hidden, since the connection can't switch workspaces. whoami still shows the current one.
• Legacy 2025 sessions belong to the URL they were opened on; using the session id on another URL returns HTTP 401.

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.

With an account API key that can reach several workspaces, use a workspace-scoped URL or add an X-Notra-Organization-Id: <workspace-id-or-slug> header (X-Organization-Id also works). The server forwards it to the Notra API on every call. A legacy 2025 session stays bound to the workspace it was initialized with; a request on that session that names a different workspace is rejected with HTTP 401, so open a new session to switch. OAuth connections ignore the header because each token is bound to the workspace chosen at consent.

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.

Hosted usage statistics

The HTTP server reports MCP usage to Notra's MCP server analytics through @usenotra/geo/mcp. Every JSON-RPC request the server answers is recorded with its method, tool name, status (ok, tool_error or rpc_error), latency, response size, session ID, and the client and server names and versions. tools/list answers also record the advertised tools. ping is skipped. Local stdio servers do not emit usage events.

Set the Notra GEO token on the hosted deployment to enable tracking:

NOTRA_GEO_TOKEN=your-geo-token

Without a token, tracking is disabled. OAuth calls are attributed to the WorkOS user_id; API-key calls carry no user. Unknown tool names are recorded as unknown. Tool arguments and results are never sent. Delivery is batched, asynchronous and best-effort: a failed delivery logs a credential-free warning without failing the tool call.

Toolsets

All 138 tools are exposed by default, which costs roughly 23k tokens of agent context (about 12k for geo alone, 11k for content). 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, or for account API keys the workspace selected with NOTRA_ORGANIZATION_ID or the X-Notra-Organization-Id header. To act in another workspace, authorize or configure a separate connection for that workspace; list_workspaces discovers access but does not switch workspaces.

Posts

To turn a pull request into a post, call generate_post with pullRequest (owner, repo, number) and optionally a brief, poll get_post_generation_status for the postId, then call create_post_pull_request to open a draft pull request with the post. Calling it again updates that pull request. A brief also works on its own to say what a post from recent activity should cover.

Post publishing schedules are separate from the content-generation schedules below. schedule_post requires an ISO 8601 scheduledAt timestamp, accepts an optional IANA timeZone (default UTC), and supports at most two external destinations. GitHub destinations use repositoryId from list_integrations and an optional merge flag (default true); social destinations use a connected X or LinkedIn accountId. Omitting destinations schedules publishing in Notra only.

Sites

Notra Sites are hosted blogs and changelogs built from a GitHub repository. Settings, domains, rollbacks and deletion stay in the dashboard. These tools need the sites.read and sites.write scopes.

publish_post_to_site always opens or updates a pull request, even when the repository publishes directly from the dashboard.

Author changes are saved to the site's blog.json as unpublished Design changes, the same draft the dashboard's Design tab shows, and go live with publish_site_design or the dashboard's Publish. Author ids are 1 to 40 lowercase letters, digits and dashes, and links must be https:// URLs. Renaming or deleting an author that is live or credited on posts needs force. publish_site_design refuses while other files on the site have unpublished changes. To credit a site author on a blog post, pass its site:<id> ref in update_post's authorIds.

Brand Identities

Integrations

Schedules

Event Triggers

Webhooks

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 personas

GEO competitors

GEO scans and visibility

GEO content briefs

Agent readiness

AI traffic

MCP server analytics

Usage of your own MCP server, reported by the @usenotra/geo SDK. Captured arguments, responses and end-user IDs stay in the dashboard.

Feedback

Review and data boundaries

All supported operations are listed upfront by tools/list. General-purpose agent execution and approval tools are not exposed because they can run dynamically discovered third-party operations. Chat history and agent sessions are available through the dashboard and API. Use the Notra dashboard for agent conversations, private-repository authentication, webhook signing secrets, and traffic tracking credentials.

Tool inputs are for task-specific business content. Do not send health records, biometric data, government identifiers, payment card information, credentials, or unrelated conversation history. Authenticate through OAuth or local configuration, never through tool arguments. Feedback accepts only the user-approved message, optional title, and feedback kind.

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 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.

CI runs typechecking, formatting checks, and the build on pull requests and pushes to main.