cohere-ai/north-mcp-python-sdk

cohere-ai/north-mcp-python-sdk

Description: An sdk for creating MCP Servers with north

Language: Python

License: MIT

Stars: 14

Forks: 10

Open issues: 7

Created: 2025-05-08T13:04:41Z

Pushed: 2026-05-26T18:26:39Z

Default branch: main

Fork: no

Archived: no

README:

North MCP Python SDK

This SDK builds on top of the original SDK. Please refer to the original repository's README for general information. This README focuses on North-specific details.

Installation

uv pip install git+ssh://git@github.com/cohere-ai/north-mcp-python-sdk.git

Why this repository

This repository provides code to enable your server to use authentication with North, a custom extension to the original specification. Other than that, no changes are made to the SDK; this builds on top of it.

Main differences

• North only supports the StreamableHTTP transport. The sse transport is deprecated, it will work for backwards compatibility, but you shouldn't use it if you are creating new servers
• You can protect all requests to your server with a secret.
• You can access the user's OAuth token to interact with third-party services on their behalf.
• You can access the user's identity (from the identity provider used with North).
• Debug mode for detailed authentication logging and troubleshooting.
• OpenTelemetry helpers for custom spans, log/trace correlation, and privacy-aware error recording (built on FastMCP telemetry).
• Built-in health check endpoint for Kubernetes liveness probes (enabled by default).

Health Check

NorthMCPServer includes a built-in /health endpoint that responds to GET requests with a 200 OK plain-text response. This is useful for Kubernetes liveness/readiness probes and load balancer health checks. The endpoint bypasses authentication, so no tokens are needed.

It is enabled by default. To disable it:

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

Examples

This repository contains example servers that you can use as a quickstart. You can find them in the examples directory.

Examples cover authentication, tool metadata for the North UI, debug mode, and OpenTelemetry (examples/telemetry-demo/).

Authentication

This SDK offers several strategies for authenticating users and authorizing their requests.

I only want north to be able to send requests to my server

mcp = NorthMCPServer(name="Demo", port=5222, server_secret="secret")

I want to get the identity of the north user that is calling my server

Refer to examples/server_with_auth.py. During your request call the following:

user = get_authenticated_user()
print(user.email)

I need access to a third party service via oauth (e.g.: google drive, slack, etc...)

Similar as above:

user = get_authenticated_user()
print(user.connector_access_tokens)

Debug Mode

The North MCP SDK includes a comprehensive debug mode that provides detailed logging of authentication processes, incoming requests, and token validation. This is invaluable when troubleshooting authentication issues.

Enabling Debug Mode

There are several ways to enable debug mode:

1. Environment Variable (Recommended)

export DEBUG=true
python your_server.py

2. Constructor Parameter

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

What Gets Logged in Debug Mode

When debug mode is enabled, you'll see detailed logs including:

• Request Headers: All incoming HTTP headers (including Authorization)
• Token Parsing: Base64 decoding and JSON parsing of auth tokens
• JWT Validation: User ID token decoding and validation steps
• Authentication Details: User email, available connectors, token counts
• Error Context: Detailed error messages with troubleshooting context

Example Debug Output

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 server_secret: True, 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: user@example.com
2024-01-15 10:30:45 - NorthMCP.AuthContext - DEBUG - Setting authenticated user in context: email=user@example.com, connectors=['google', 'slack']

Debug Mode Examples

See examples/server_with_debug.py for a runnable example.

Security Note

Debug mode logs sensitive information including request headers and token metadata. Never enable debug mode in production environments as it may expose authentication details in logs.

OpenTelemetry

FastMCP 3 emits a span for each tool call when a TracerProvider is configured. The North SDK adds helpers on top of that; it does not install exporters or configure where traces are sent — opentelemetry-sdk and OTLP exporters are not bundled dependencies. Servers run fine without a TracerProvider; traces become no-ops until you add one.

What the SDK provides

| Helper | Purpose | |--------|---------| | TelemetryConfig | Opt-in config object for the telemetry integration (sensitive-data policy, log/trace correlation) | | mcp.telemetry.traced_span | Custom spans nested under FastMCP tool spans, driven by the server's TelemetryConfig. Use this when you have mcp in scope. | | traced_span (module-level) | Same context manager, but auto-resolves the active server's config via fastmcp.server.dependencies.get_server. Use this from tool bodies that don't hold an mcp reference. | | get_telemetry_config() | Returns the active NorthMCPServer's TelemetryConfig (or a private "off" config when there's no active North server). Lets tools branch on record_sensitive_data without an mcp reference. | | Depends | Re-export of FastMCP's Depends factory. Combine with get_telemetry_config for FastAPI-style…