North MCP Python SDK

North MCP Python SDK

この SDK は元の SDK を基盤として構築されています。一般的な情報については、元のリポジトリの README を参照してください。この README では、North 固有の詳細に焦点を当てています。

インストール

uv pip install git+ssh://[email protected]/cohere-ai/north-mcp-python-sdk.git

このリポジトリについて

このリポジトリでは、元の仕様を独自に拡張した North で認証を使用できるようにするコードを提供しています。それ以外に SDK への変更はなく、この SDK は元の SDK を基盤として構築されています。

主な違い

• North がサポートするのは StreamableHTTP トランスポートのみです。sse トランスポートは非推奨です。後方互換性のために動作しますが、新しいサーバーを作成する場合は使用しないでください
• ID トークンで North ユーザーの ID を検証でき、本番環境では trusted_issuers を使用して受け入れる ID プロバイダーを任意で制限できます。
• ユーザーに代わってサードパーティサービスと連携するため、ユーザーの OAuth トークンにアクセスできます。
• ユーザーの ID（North で使用される ID プロバイダーから取得）にアクセスできます。
• デバッグモードで、認証の詳細なログ記録とトラブルシューティングを行えます。
• OpenTelemetry ヘルパーで、カスタムスパン、ログとトレースの相関付け、プライバシーに配慮したエラー記録を行えます（FastMCP telemetry を基盤としています）。
• Kubernetes のライブネスプローブ用の組み込みヘルスチェックエンドポイント（デフォルトで有効）。

ヘルスチェック

NorthMCPServer には組み込みの /health エンドポイントがあり、GET リクエストに対してプレーンテキストの 200 OK 応答を返します。Kubernetes のライブネス／レディネスプローブやロードバランサーのヘルスチェックに便利です。このエンドポイントは認証をバイパスするため、トークンは不要です。

デフォルトで有効です。無効にするには、次のようにします。

mcp = NorthMCPServer(name="Demo", health_check=False)

例

このリポジトリには、クイックスタートとして使用できるサーバーの例が含まれています。examples ディレクトリにあります。

例では、認証、North UI 用のツールメタデータ、デバッグモード、OpenTelemetry（examples/telemetry-demo/）を取り上げています。

認証

この SDK では、ユーザーの認証とリクエストの認可に、いくつかの方法を利用できます。

サーバーへのリクエスト送信を North だけに許可したい場合

North はリクエストに X-North-ID-Token を付与します。本番環境では、 サーバーがトークンの発行元を想定される ID プロバイダーと照合できるよう、 trusted_issuers を設定してください。ローカル開発環境やリスクの低い環境では、 この設定は任意であり、トークンは署名を検証せずにデコードされます。

mcp = NorthMCPServer(
    name="Demo",
    port=5222,
    trusted_issuers=["https://your-idp.example.com"],
)

サーバーを呼び出している North ユーザーの ID を取得したい場合

examples/server_with_auth.py を参照してください。リクエスト内で次のように呼び出します。

user = get_authenticated_user()
print(user.email)

OAuth 経由でサードパーティサービス（例：Google Drive、Slack など）にアクセスする必要がある場合

上記と同様です。

user = get_authenticated_user()
print(user.connector_access_tokens)

デバッグモード

North MCP SDK には、認証処理、受信リクエスト、トークン検証の詳細なログを提供する包括的なデバッグモードが含まれています。認証の問題をトラブルシューティングする際に非常に役立ちます。

デバッグモードを有効にする

デバッグモードを有効にする方法はいくつかあります。

1. 環境変数（推奨）

export DEBUG=true
python your_server.py

2. コンストラクターパラメーター

mcp = NorthMCPServer(name="Demo", port=5222, debug=True)

デバッグモードで記録される内容

デバッグモードを有効にすると、次のような詳細なログが表示されます。

• リクエストヘッダー：受信したすべての HTTP ヘッダー（Authorization を含む）
• トークンの解析：認証トークンの Base64 デコードと JSON 解析
• JWT 検証：ユーザー ID トークンのデコードと検証手順
• 認証の詳細：ユーザーのメールアドレス、利用可能なコネクター、トークン数
• エラーのコンテキスト：トラブルシューティングの情報を含む詳細なエラーメッセージ

デバッグ出力の例

2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Authenticating request from ('127.0.0.1', 54321)
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Request headers: {'authorization': 'Bearer eyJ...', 'content-type': 'application/json'}
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Authorization header present (length: 248)
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Successfully decoded base64 auth header
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Successfully parsed auth tokens. Has user_id_token: True, Connector count: 2
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Available connectors: ['google', 'slack']
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Successfully decoded user ID token. Email: [email protected]
2024-01-15 10:30:45 - NorthMCP.AuthContext - DEBUG - Setting authenticated user in context: [email protected], connectors=['google', 'slack']

デバッグモードの例

実行可能な例については、examples/server_with_debug.py を参照してください。

セキュリティに関する注意

デバッグモードでは、リクエストヘッダーやトークンのメタデータなどの機密情報がログに記録されます。ログに認証情報が漏れるおそれがあるため、本番環境ではデバッグモードを有効にしないでください。

OpenTelemetry

TracerProvider が設定されている場合、FastMCP 3 はツール呼び出しごとにスパンを出力します。North SDK はその上にヘルパーを追加しますが、エクスポーターをインストールしたり、トレースの送信先を設定したりすることはありません。opentelemetry-sdk と OTLP エクスポーターは依存関係に含まれていません。サーバーは TracerProvider がなくても問題なく動作し、追加するまではトレースは何も行いません。

SDK が提供するもの

ヘルパー	用途
TelemetryConfig	テレメトリー統合のオプトイン設定オブジェクト（機密データのポリシー、ログ／トレースの相関）
mcp.telemetry.traced_span	FastMCP のツールスパン内にネストされるカスタムスパン。サーバーの TelemetryConfig に基づいて動作します。mcp を参照できる場合に使用します。
traced_span （モジュールレベル）	同じコンテキストマネージャーですが、fastmcp.server.dependencies.get_server を使ってアクティブなサーバーの設定を自動的に解決します。mcp への参照を保持しないツール本体で使用します。
get_telemetry_config()	アクティブな NorthMCPServer の TelemetryConfig を返します（アクティブな North サーバーがない場合は、プライベートな「オフ」設定を返します）。mcp への参照がなくても、record_sensitive_data に応じた分岐ができます。
Depends	FastMCP の Depends ファクトリーを再エクスポートしたものです。get_telemetry_config と組み合わせると、FastAPI スタイルのパラメーター注入ができます。例：telemetry: TelemetryConfig = Depends(get_telemetry_config)。
get_tracer	FastMCP のトレーサー（計測名は fastmcp）を再エクスポートしたものです。
TraceContextFormatter	スパンがアクティブなとき、NorthMCP.{name} ロガーのログ行に trace_id ／ span_id を追加します。

セットアップ

1. NorthMCPServer をインポートする前に、main で TracerProvider とエクスポーターを登録します（FastMCP はインポート時にグローバルプロバイダーを読み込みます）。独自のセットアップ、または標準の OTel 環境変数（OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_SERVICE_NAME など）を使用します。
2. TelemetryConfig を NorthMCPServer に渡します。これがオプトインを示すシグナルです。log_trace_context が有効な場合（オプトインした設定ではデフォルトで有効）、トレース／スパン ID が NorthMCP.* のログ行に自動的に追加されます。
3. Depends(get_telemetry_config) を使って設定をツールに注入し、カスタムスパンには telemetry.traced_span(...) を呼び出します。mcp.telemetry と直接インポートする方法については、ヘルパーの表を参照してください。

def configure_tracing() -> None:
    # Install opentelemetry-sdk + exporters in your server project.
    # See examples/telemetry-demo/main.py for a minimal OTLP gRPC example.
    ...

def main() -> None:
    configure_tracing()

    from north_mcp_python_sdk import (
        Depends,
        NorthMCPServer,
        TelemetryConfig,
        get_telemetry_config,
    )

    mcp = NorthMCPServer(
        "Search",
        telemetry=TelemetryConfig(
            record_sensitive_data=False,
            log_trace_context=True,
        ),
    )

    @mcp.tool()
    async def search(
        query: str,
        telemetry: TelemetryConfig = Depends(get_telemetry_config),
    ) -> list[dict]:
        # FastMCP injects the active server's TelemetryConfig as `telemetry`
        # before the tool body runs. No reference to `mcp` is needed, and
        # `telemetry.traced_span` honours `record_sensitive_data` for
        # exception details.
        with telemetry.traced_span(
            "search.provider_call",
            attributes={"search.query_length": len(query)},
        ) as span:
            if telemetry.record_sensitive_data:
                span.add_event("search.query", {"query": query})

            results = await provider.search(query)
            span.set_attribute("search.result_count", len(results))
            return results

デフォルト値で Depends(...) を使用すると、ruff の B008 と basedpyright の reportCallInDefaultInitializer に抵触します。このリポジトリの pyproject.toml に設定されているとおりに Depends を許可リストに追加してください。これは FastAPI プロジェクトでも使われている方法です。

詳しい手順については、examples/telemetry-demo/main.py を参照してください。HTTP やロギングなど、より広範な自動計測には、FastMCP のテレメトリードキュメントに従って opentelemetry-instrument CLI を使用してください。

TelemetryConfig のオプション

オプション	デフォルト値（オプトイン時）	説明
record_sensitive_data	False	True の場合、traced_span はスパンに例外メッセージ全体を記録し、ツールは機密ペイロード（クエリテキスト、ID など）をスパンイベントとして追加できます。安全性を考慮してデフォルトでは無効です。コード内でのみ明示的にオプトインしてください。
log_trace_context	True	True の場合、SDK はフォーマッターを設定し、スパンがアクティブな間、NorthMCP.* ロガーのログ行に trace_id ／ span_id を追加します。

telemetry=None の場合、SDK は内部の「テレメトリーにオプトインしていない」設定を使用します。両方のフラグが False になり、NorthMCP.* ロガーにはフォーマッターが設定されず、エラー発生時に traced_span が記録するのは例外の型名だけです。どちらのフラグにも環境変数によるフォールバックはありません。FastMCP 自体のツール／リソース／プロンプトのスパンには影響しません。TracerProvider が設定されていれば、引き続きスパンが表示されます。

mcp = NorthMCPServer(
    name="Demo",
    telemetry=TelemetryConfig(record_sensitive_data=True),
)

North を使用しないローカル開発

このガイドでは、North に接続せずに MCP サーバーをローカルでテストする方法を説明します。そのために、MCP Inspector を使用します。次のコマンドで実行できます。

npx @modelcontextprotocol/inspector

認証が不要で、ローカルで実行するだけの場合は、stdio トランスポートを選択できます。MCP Inspector に移動し、次のように設定します。

• トランスポートタイプ：stdio
• コマンド：uv
• 引数：run examples/server_with_auth.py --transport stdio

次に、以下の操作を行います。

• 「Connect」をクリックします。
• 画面上部の「Tools」を選択します。
• 「List Tools」→「add」をクリックします。
• 数値を入力して「Run」をクリックします。合計が表示されます。

認証の追加

認証の仕組みをローカルでテストする場合は、次の手順を実行します。まず、streamable http トランスポートでサーバーを起動します。

uv run examples/server_with_auth.py --transport streamable-http

次に、ベアラートークンを作成します。examples/create_bearer_token.py を使って生成するか、あらかじめ用意されたものを使用できます。

MCP Inspector に移動し、次のように設定します。

• トランスポートタイプ：Streamable HTTP
• URL：http://localhost:5222/mcp
• Authentication → Bearer token：eyJzZXJ2ZXJfc2VjcmV0IjogInNlcnZlcl9zZWNyZXQiLCAidXNlcl9pZF90b2tlbiI6ICJleUpoYkdjaU9pSklVekkxTmlJc0luUjVjQ0k2SWtwWFZDSjkuZXlKbGJXRnBiQ0k2SW5SbGMzUkFZMjl0Y0dGdWVTNWpiMjBpZlEuV0pjckVUUi1MZnFtX2xrdE9vdjd0Q1ktTmZYR2JuYTVUMjhaeFhTaEZ4SSIsICJjb25uZWN0b3JfYWNjZXNzX3Rva2VucyI6IHsiZ29vZ2xlIjogImFiYyJ9fQ==

前と同じ手順を行います。ツールを呼び出すと、サーバーを起動したターミナルに次のログが表示されます。

This tool was called by: [email protected]

開発

前提条件

このプロジェクトに貢献するには、次のものが必要です。

• Python 3.11+：SDK に必要です
• uv >= 0.8.13：依存関係の管理、フォーマット、CI チェックに使用します

セットアップ

1. リポジトリをクローンします。

   git clone https://github.com/cohere-ai/north-mcp-python-sdk.git
   cd north-mcp-python-sdk
   

2. 依存関係をインストールします。

   uv sync --dev
   

コードのフォーマット

このプロジェクトでは、一貫したコードフォーマットのために uv format を使用しています。CI パイプラインでは、次の基準が適用されます。

# Check formatting (same as CI)
uv format --preview-features format --check

# Apply formatting
uv format --preview-features format

テストの実行

uv run pytest

コントリビューション

PR を送信する前に、次のことを行ってください。

1. コードがフォーマットチェックに合格することを確認します：uv format --preview-features format --check
2. テストスイートを実行します：uv run pytest
3. 既存のコードスタイルとパターンに従います