Notra

Notra MCP サーバー

Notra API 用の MCP（Model Context Protocol）サーバーです。投稿、ブランドアイデンティティ、連携、スケジュール、GEO 可視性スキャン、競合他社、コンテンツブリーフ、AI トラフィック分析を管理します。

セットアップ

Notra ワークスペースのダッシュボードの Developer > API Keys から API キーを生成できます。

Node.js 20 以降が必要です。

Claude Desktop

~/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

Claude Code を起動する前に、シェルで NOTRA_API_KEY 環境変数を設定してください。

Codex

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

codex mcp list を実行して、接続を確認します。Codex CLI、デスクトップアプリ、IDE 拡張機能は、この MCP 設定を共有します。

OpenCode

シェルで NOTRA_API_KEY を設定してから、プロジェクトレベルの opencode.json またはグローバルの ~/.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

amp config edit を実行して設定に以下を追加するか、ワークスペース固有の設定として .amp/settings.json に配置します。

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

Amp を起動する前に、環境変数に NOTRA_API_KEY を設定してください。ワークスペースの MCP サーバーでは、amp mcp approve notra による承認が必要な場合があります。

アカウント API キー

アカウント API キーは特定のワークスペースではなく、ユーザーに紐づいているため、メンバーになっているすべてのワークスペースで使用できます。複数のワークスペースに所属している場合は、NOTRA_ORGANIZATION_ID でこのサーバーが操作するワークスペースを選択します。

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

指定しない場合、ツールはワークスペースの選択を求めるメッセージを表示して失敗します。list_workspaces は選択なしで使用でき、ID が表示されます。組織 API キーでは NOTRA_ORGANIZATION_ID は無視されます。

リモート MCP（OAuth）

ホスト型のストリーマブル HTTP サーバー https://mcp.usenotra.com/mcp は、主要な認証方式として OAuth を使用します。現在の 2026-07-28 MCP プロトコルと、レガシーの 2025 クライアントの両方をサポートしています。MCP クライアントは、以下で保護されたリソースのメタデータを検出してください。

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

このメタデータは、Notra 認可サーバー（WorkOS AuthKit）https://oauth.usenotra.com を参照します。このサーバーは動的クライアント登録（RFC 7591）をサポートしています。MCP サーバーは、認可サーバーのメタデータを https://mcp.usenotra.com/.well-known/oauth-authorization-server にも複製しています。

ワークスペース指定 URL

URL にワークスペース ID またはスラッグを追加すると、接続先を特定のワークスペースに固定できます：https://mcp.usenotra.com/mcp/<workspace>。これは、URL のみを受け付け、カスタムヘッダーを送信できないクライアントでワークスペースを選択する方法です。

• 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）：

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

ワークスペース指定 URL の場合：

• API キーはそのワークスペースで動作します。URL は X-Notra-Organization-Id ヘッダーより優先されます。組織キーは自身のワークスペースの URL でのみ機能し、他のワークスペースは Notra API によって HTTP 403 で拒否されます。
• OAuth は /mcp と同様に機能しますが、認可するワークスペースは URL に指定されたワークスペースと一致している必要があります。一致しない場合、別のワークスペースで暗黙的に操作するのではなく、リクエストが HTTP 403 で拒否されます。OAuth チャレンジは /mcp と同じリソースを通知するため、クライアントには通常の Notra トークンが発行されます。URL のワークスペースは、認可するワークスペースによって強制されます。
• 接続先のワークスペースを切り替えられないため、list_workspaces は非表示になります。whoami には引き続き現在のワークスペースが表示されます。
• レガシー 2025 セッションは、開始された URL に紐づきます。別の URL でセッション ID を使用すると HTTP 401 が返されます。

API キーの代替手段

リモート接続では、静的な Authorization: Bearer … ヘッダーとして Notra API キーを使用することもできます。Notra ワークスペースのダッシュボードで「Developer > API Keys」からキーを生成してください。OAuth 対応クライアントでは、手動でキーを設定する代わりに OAuth フローを使用してください。

複数のワークスペースにアクセスできるアカウント API キーを使用する場合は、ワークスペーススコープの URLを使うか、X-Notra-Organization-Id: <workspace-id-or-slug> ヘッダーを追加してください（X-Organization-Id も使用できます）。サーバーはすべての呼び出しでこのヘッダーを Notra API に転送します。レガシー 2025 セッションは、初期化時に指定したワークスペースに紐付けられたままです。そのセッションで別のワークスペースを指定するリクエストは HTTP 401 で拒否されるため、切り替えるには新しいセッションを開始してください。OAuth 接続では、各トークンが同意時に選択したワークスペースに紐付けられているため、このヘッダーは無視されます。

セルフホスト型 HTTP デプロイメントでは、OAuth の検証を次のように設定できます。

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

発行者は https://{WORKOS_AUTHKIT_DOMAIN} であり、AuthKit が発行したトークンの iss クレームと一致している必要があります。一致しない場合、すべてのベアラートークンが拒否されます。トークン署名は https://{WORKOS_AUTHKIT_DOMAIN}/oauth2/jwks を使って検証されます。

NODE_ENV=development の場合、AuthKit ドメインのデフォルト値は essential-berry-67-development-2.authkit.app です。本番環境では oauth.usenotra.com がデフォルトです。auth.usenotra.com は WorkOS Authentication API のドメインであり、OAuth エンドポイントを提供していないため、この用途では機能しません。

レガシー 2025 セッションは、30 分間操作がないと期限切れになります。各 OAuth ユーザーまたは API キーが保持できるセッション数は NOTRA_MCP_MAX_SESSIONS_PER_PRINCIPAL で指定します（デフォルトは 50）。上限を超えると、そのユーザーまたは API キーの最も長い間使用されていないセッションが閉じられます。サーバーが NOTRA_MCP_MAX_SESSIONS セッションを保持している場合（デフォルトは 1000）、ほかのユーザーのセッションを閉じる代わりに、新しいセッションは HTTP 503 と Retry-After を返して拒否されます。

ホスト型の使用統計

HTTP サーバーは PostHog だけを使って使用状況を追跡し、ディスパッチされたツール呼び出しごとに mcp_tool_called イベントを送信します。これには、ツールの入力／出力検証に失敗した呼び出しや、HTTP 200 で isError: true を返す呼び出しも含まれます。初期化、ディスカバリー、ヘルスチェック、ツールのディスパッチ前に拒否されたリクエストはカウントされません。ローカルの stdio サーバーは使用イベントを送信せず、PostHog に接続することもありません。

追跡を有効にするには、ホスト型デプロイメントに PostHog プロジェクトトークンを設定してください。

POSTHOG_PROJECT_TOKEN=your-project-token

POSTHOG_HOST のデフォルト値は https://us.i.posthog.com です。EU プロジェクトでは https://eu.i.posthog.com を設定してください。プロジェクトトークンがない場合、追跡は無効になります。代替のコレクターや JSON 使用状況ログへのフォールバックはありません。

イベントには tool_name、outcome（success、error、cancelled のいずれか）、duration_ms、server_version、protocol_version、client_name、client_version、auth_kind が含まれます。OAuth イベントには、検証済みの WorkOS organization_id と user_id も含まれます。API キーによる呼び出しにはユーザー／ワークスペースの帰属情報がなく、PostHog の distinct ID mcp:api-key が共有されます。この ID をユニークユーザーとしてカウントしてはいけません。クライアント ID は自己申告に基づいて既知のクライアント名に分類され、未知の名前は other として記録されます。バージョンは数値形式の major.minor.patch のみ保持されます。未知のツール名は unknown として記録されます。

引数、結果、プロンプト、エラーメッセージ、ヘッダー、IP アドレス、トークン、API キー、トークンハッシュが使用イベントに含まれることはありません。イベントは非同期でベストエフォートにより配信され、タイムアウトは 5 秒、プロセスごとの PostHog リクエスト保留数は最大 64 件です。配信に失敗した場合や配信が破棄された場合は、ツール呼び出しを失敗させることなく、認証情報を含まない警告が出力されます。イベントのサンプリングは行われませんが、PostHog への配信は監査台帳や請求台帳ではありません。

PostHog では mcp_tool_called で絞り込み、tool_name、client_name、outcome で分類してください。OAuth 呼び出しのみを対象に organization_id／user_id の個別数をカウントし、レイテンシのパーセンタイルには duration_ms を使用してください。

ツールセット

96 個すべてのツールがデフォルトで公開されており、エージェントのコンテキストをおよそ 20k トークン消費します。必要なものだけを読み込むには、NOTRA_MCP_TOOLSETS（stdio および HTTP）またはリモートエンドポイントの toolsets クエリパラメーターでツールセットを選択してください。

ツールセット	ツール
content	投稿、ブランドアイデンティティ、インテグレーション、スケジュール、イベントトリガー、スキル、フィードバック受信トレイ
geo	プロジェクトおよびすべての GEO ツール

ワークスペースツールと submit_feedback は常に利用できます。

NOTRA_MCP_TOOLSETS=content npx -y @usenotra/mcp

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

ツール

ワークスペース

ツール	説明
whoami	現在のワークスペースと認証済みアカウントの情報を表示します
list_workspaces	認証済みアカウントが利用できる承認済みおよび保留中のワークスペースを一覧表示します

各 MCP 接続は、ベアラートークンに紐付けられたワークスペース、またはアカウント API キーの場合は NOTRA_ORGANIZATION_ID もしくは X-Notra-Organization-Id ヘッダーで選択されたワークスペースで動作します。別のワークスペースで操作するには、そのワークスペース用に別の接続を認証または設定してください。list_workspaces でアクセス権を確認できますが、ワークスペースは切り替わりません。

投稿

ツール	説明
list_posts	並べ替え、ページネーション、ステータス、コンテンツタイプ、ブランドアイデンティティの任意のフィルターを使って投稿の概要を一覧表示します
get_post	ID で単一の投稿を取得します
create_post	独自のタイトルと Markdown から投稿を作成します
update_post	投稿のタイトル、Markdown、またはステータスを更新します
delete_post	投稿を削除します
generate_post	GitHub のアクティビティから投稿生成を非同期でキューに登録します
get_post_generation_status	投稿生成ジョブのステータスを確認します
get_post_schedule	投稿の公開スケジュールと、公開先ごとのステータスを取得します
schedule_post	既存の投稿を Notra で公開するようスケジュールし、オプションで GitHub、X、または LinkedIn への公開も設定します
cancel_post_schedule	保留中の公開先をキャンセルします。公開処理がすでに進行中の公開先は、そのまま処理が完了します

投稿公開のスケジュールは、以下のコンテンツ生成スケジュールとは別です。schedule_post では ISO 8601 形式の scheduledAt タイムスタンプが必要です。任意の IANA timeZone（デフォルトは UTC）を指定でき、外部の公開先は最大 2 つまで対応しています。GitHub の公開先では list_integrations の repositoryId と、任意の merge フラグ（デフォルトは true）を使用します。ソーシャルメディアの公開先では、接続済みの X または LinkedIn の accountId を使用します。公開先を省略すると、Notra のみで公開がスケジュールされます。

ブランドアイデンティティ

ツール	説明
list_brand_identities	すべてのブランドアイデンティティを一覧表示します
get_brand_identity	IDを指定して単一のブランドアイデンティティを取得します
update_brand_identity	ブランドアイデンティティの設定を更新します
delete_brand_identity	ブランドアイデンティティを削除します
list_brand_colors	ブランドアイデンティティのガイドラインカラーを一覧表示します
create_brand_color	ブランドカラーを追加します
update_brand_color	ブランドカラーを更新します
delete_brand_color	ブランドカラーを削除します
generate_brand_identity	ウェブサイトのURLからブランドアイデンティティの生成を非同期でキューに登録します
get_brand_identity_generation_status	ブランドアイデンティティ生成ジョブのステータスを確認します

インテグレーション

ツール	説明
list_integrations	有効なGitHubおよびLinearのインテグレーションを一覧表示します
create_github_integration	公開GitHubリポジトリに接続します
delete_integration	GitHubまたはLinearのインテグレーションを削除します

スケジュール

ツール	説明
list_schedules	スケジュール済みのコンテンツ生成ジョブを一覧表示します
create_schedule	スケジュール済みのコンテンツ生成ジョブを作成します
update_schedule	スケジュール済みのコンテンツ生成ジョブを更新します
delete_schedule	スケジュール済みのコンテンツ生成ジョブを削除します

イベントトリガー

ツール	説明
list_event_triggers	GitHubのリリースまたはプッシュをもとにコンテンツを生成するトリガーを一覧表示します
get_event_trigger	IDを指定して単一のイベントトリガーを取得します
create_event_trigger	イベントトリガーを作成します
update_event_trigger	イベントトリガーの設定を置き換えます
delete_event_trigger	イベントトリガーを削除します

Webhook

ツール	説明
list_webhook_endpoints	Notraのイベントを購読するHTTPSエンドポイントを一覧表示します
delete_webhook_endpoint	Webhookの購読を解除し、未送信の配信をキャンセルします
list_webhook_deliveries	Webhookの配信を一覧表示します。ステータスによる絞り込みも可能です
get_webhook_delivery	配信のペイロードと試行履歴を取得します
retry_webhook_delivery	失敗したWebhookの配信を再試行します

スキル

ツール	説明
list_skills	再利用可能な執筆スキルを一覧表示します
get_skill	名前を指定して単一のスキルを取得します
create_skill	再利用可能な執筆スキルを作成します
update_skill	再利用可能な執筆スキルを更新します
delete_skill	再利用可能な執筆スキルを削除します

プロジェクト

GEO の機能はプロジェクトごとに設定されます。ほとんどの GEO ツールでは projectId が必要です。まず list_projects を呼び出して確認してください。GEO ツールを利用するには、組織に紐づく API キーと GEO プランが必要です。

Tool	Description
list_projects	組織の GEO プロジェクトを一覧表示します
get_project	ID を指定して単一のプロジェクトを取得します
create_project	プロジェクトを作成します。ブランドとの紐付けは任意です
update_project	プロジェクト名を変更するか、ブランドアイデンティティとの紐付けを変更します
delete_project	プロジェクトと、そのすべての GEO データを削除します（連鎖削除）

GEO 設定

Tool	Description
get_geo_settings	トラッキング対象の会社、別名、言語、エンジン、スキャン設定を取得します
list_geo_engines	プロジェクトでトラッキングできるエンジン ID を一覧表示します
update_geo_settings	設定ドキュメントを置き換え、スキャンサイクルを再開します

GEO プロンプトとシーケンス

Tool	Description
list_geo_prompts	トラッキング中のプロンプト（カスタムおよび自動生成）を一覧表示します
create_geo_prompt	新しいプロンプトをトラッキング対象に追加します
update_geo_prompt	トラッキング中のプロンプトを有効または無効にします
delete_geo_prompt	プロンプトのトラッキングを停止します
import_geo_prompts	行データまたは CSV からプロンプトを一括インポートします
list_geo_sequences	複数ターンのプロンプトシーケンスを一覧表示します
create_geo_sequence	プロンプトシーケンスを作成します
update_geo_sequence	シーケンスの名前、ステップ、または有効状態を更新します
delete_geo_sequence	シーケンスを削除します
run_geo_sequence	シーケンスを今すぐ同期実行します（AI クレジットを使用し、数分かかる場合があります）

GEO 競合他社

Tool	Description
list_geo_competitors	トラッキング中の競合他社を一覧表示します
upsert_geo_competitor	競合他社を作成、更新、または名前変更します
suggest_geo_competitors	AI でドメインに基づく有力な競合他社を特定します
delete_geo_competitor	競合他社のトラッキングを停止します
import_geo_competitors	行データまたは CSV から競合他社を一括インポートします

GEO スキャンと可視性

ツール	説明
create_geo_scan	非同期の可視性スキャンを開始します（AI クレジットを使用します）
list_geo_scans	ページネーションでスキャンを一覧表示します
get_geo_scan	スキャンとそのステータスを取得します
get_geo_snapshot	複数のシグナルを横断した簡潔な診断と、推奨される次のアクションを取得します
get_geo_changes	最新の 2 件のスキャン間の変更を取得します
get_geo_visibility_overview	回答エンジンごとの言及率を取得します
get_geo_visibility_timeseries	エンジンごとの日別の言及数を取得します
list_geo_prompt_result_summaries	回答全文や URL を含まない、フィルター済みのページネーション付き結果を取得します
get_geo_prompt_result_detail	1 件のチェックについて、回答全文と情報源を取得します
get_geo_prompt_history	1 つのプロンプトの簡潔な過去のチェック結果を取得します
get_geo_sentiment	感情指標と前期間との比較を取得します
get_geo_sentiment_analysis	保存されたテーマ別の感情分析を取得します
list_geo_sentiment_evidence	感情指標の根拠となる回答をページネーションで取得します
list_geo_shelf_sources	ページネーション付きの引用ソース一覧と機会の状態を取得します
get_geo_competitor_share	ブランドフィルターと件数制限を指定して、シェア・オブ・ボイス上位のブランドを取得します
get_geo_language_share	トラッキング対象言語ごとの言及率を取得します
get_geo_competitor_detail	1 社の競合他社について、言及履歴と、それを促しているプロンプトを取得します

GEO コンテンツブリーフ

ツール	説明
list_geo_content_gaps	競合他社は言及されているものの、このブランドは言及されていないプロンプトを取得します
list_geo_content_briefs	コンテンツブリーフとそのステータスを一覧表示します
plan_geo_content_brief	トピックを調査してブリーフを作成します（課金対象で、数分かかる場合があります）
get_geo_content_brief	ドキュメント全文とライターのステータスを含むブリーフを取得します
update_geo_content_brief	下書きブリーフのアウトラインと計画フィールドを編集します
approve_geo_content_brief	ブリーフを承認して記事ライターを開始します

エージェントの対応状況

ツール	説明
get_geo_agent_readiness	最新の対応状況レポート、スコア履歴、実行中のスキャンを取得します
start_geo_agent_readiness_scan	プロジェクトのウェブサイトの対応状況スキャンをキューに追加します

AI トラフィック

ツール	説明
get_geo_traffic_overview	クローラーと AI リファラーの合計、情報源、日別の時系列データを取得します
get_geo_traffic_log	直近の個別の AI クローラー／リファラーのリクエストを取得します
list_geo_traffic_journeys	ジャーニーごとにグループ化されたセッションを一覧表示します
get_geo_traffic_journey	1 つのジャーニーに含まれるすべてのイベントを取得します
list_geo_traffic_pages	AI トラフィックによる訪問数が多いページを一覧表示します
get_geo_ingest_setup	トラッキングのインストール用スニペットと取り込みエンドポイントを取得します

フィードバック

ツール	説明
submit_feedback	バグ報告、機能リクエスト、質問、称賛をNotraの受信トレイに送信します（認証不要）
list_feedback	ステータス、種類、プロジェクト別に、組織が受け取ったフィードバックを一覧表示します
get_feedback	エージェントのメタデータとともに、1件のフィードバックを取得します
update_feedback	フィードバックのトリアージステータスを設定します

レビューとデータの境界

サポートされるすべての操作は、tools/list に事前に記載されています。汎用エージェント実行ツールと承認ツールは、動的に検出されたサードパーティーの操作を実行できるため、公開されていません。チャット履歴とエージェントセッションは、ダッシュボードとAPIから利用できます。エージェントとの会話、プライベートリポジトリの認証、Webhook署名シークレット、トラフィック追跡の認証情報には、Notraダッシュボードを使用してください。

ツールの入力は、タスク固有の業務内容を対象としています。健康記録、生体認証データ、政府発行の識別番号、決済カード情報、認証情報、無関係な会話履歴は送信しないでください。認証にはOAuthまたはローカル設定を使用し、ツール引数を通じて認証しないでください。フィードバックで受け付けるのは、ユーザーが承認したメッセージ、任意のタイトル、フィードバックの種類のみです。

開発

Node 22.12+（Node 22）またはNode 24と、package.json で固定されているpnpmのバージョンを使用してください。

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

src/schemas/api-responses.ts のツール出力スキーマは、Notra OpenAPI仕様から生成されます。APIの変更後に pnpm run generate:output-schemas を実行してください。ファイルが最新でない場合、CIは失敗します。

VitestはZodコンパイルを有効にして、ソースに対して直接実行されます。CIでは、プルリクエストと main へのプッシュ時に、テスト、型チェック、フォーマットチェック、ビルドが実行されます。