Power your agent
Cài đặt từ nhà phát hành. Không phải endpoint của PlugMCP.
Host a copy with our keys and logs.
Chưa có bản phát hành đóng gói nào trong registry. Làm theo README của kho mã.
URL từ xa hay một lệnh trên máy của bạn? Hai cách cài đặt khác nhau thế nào
Chạy trên PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
MởTừ nhà phát hành
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.
uv pip install git+ssh://[email protected]/cohere-ai/north-mcp-python-sdk.git
An sdk for creating MCP Servers with north
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.
trusted_issuers for production.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)
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/).
This SDK offers several strategies for authenticating users and authorizing their requests.
North sends an X-North-ID-Token with requests. For production, configure
trusted_issuers so your server verifies that token was issued by an expected
identity provider. For local development or lower-risk setups, this setting is
optional and tokens are decoded without signature verification.
mcp = NorthMCPServer(
name="Demo",
port=5222,
trusted_issuers=["https://your-idp.example.com"],
)
Refer to examples/server_with_auth.py. During your request call the following:
user = get_authenticated_user()
print(user.email)
Similar as above:
user = get_authenticated_user()
print(user.connector_access_tokens)
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.
There are several ways to enable debug mode:
export DEBUG=true
python your_server.py
mcp = NorthMCPServer(name="Demo", port=5222, debug=True)
When debug mode is enabled, you'll see detailed logs including:
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']
See examples/server_with_debug.py for a runnable example.
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.
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.
TracerProvider and exporters in main before importing NorthMCPServer (FastMCP reads the global provider at import time). Use your own setup or standard OTel env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, etc.).TelemetryConfig to NorthMCPServer — this is the opt-in signal. When log_trace_context is enabled (the default for an opted-in config), trace/span IDs are appended automatically to NorthMCP.* log lines.Depends(get_telemetry_config) and call telemetry.traced_span(...) for custom spans. See the helper table for mcp.telemetry and bare-import alternatives.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(...) in a default trips ruff's B008 and basedpyright's reportCallInDefaultInitializer. Whitelist Depends as configured in this repo's pyproject.toml; this is the same approach FastAPI projects use.
Full walkthrough: examples/telemetry-demo/main.py. For broader auto-instrumentation (HTTP, logging, etc.), use the opentelemetry-instrument CLI per FastMCP telemetry docs.
TelemetryConfig optionsIf you leave telemetry=None, the SDK uses an internal "telemetry not opted in" config: both flags False, no formatter is attached to the NorthMCP.* logger, and traced_span records only the exception type name on error. Neither flag has an environment-variable fallback. FastMCP's own tool/resource/prompt spans are unaffected — they still appear whenever a TracerProvider is configured.
mcp = NorthMCPServer(
name="Demo",
telemetry=TelemetryConfig(record_sensitive_data=True),
)
This guide describes how to test your MCP server locally without connecting it to North. For this, we will use the MCP Inspector. You can run it with:
npx @modelcontextprotocol/inspector
If authentication is not required and you just want to run it locally, you can choose the stdio transport. Navigate to the MCP Inspector and configure it as follows:
From here:
If you want to test the authentication mechanism locally you can do the following. First start the server with the streamable http transport:
uv run examples/server_with_auth.py --transport streamable-http
Next, create a bearer token. You can generate one using examples/create_bearer_token.py or use a pre-made one.
Navigate to the MCP Inspector and configure it like this:
Follow the same process as before. When you call the tool, you should see the following log in the terminal where you started the server:
This tool was called by: [email protected]
To contribute to this project, you'll need:
Clone the repository:
git clone https://github.com/cohere-ai/north-mcp-python-sdk.git
cd north-mcp-python-sdk
Install dependencies:
uv sync --dev
This project uses uv format for consistent code formatting. The CI pipeline enforces these standards:
# Check formatting (same as CI)
uv format --preview-features format --check
# Apply formatting
uv format --preview-features format
uv run pytest
Before submitting a PR:
uv format --preview-features format --checkuv run pytestAn sdk for creating MCP Servers with north
Công cụ
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Bản ghi này không liệt kê biến môi trường bắt buộc nào.
North MCP Python Sdk chạy cục bộ qua stdio.
Kiểm tra lần cuối: 2026-11-05. An sdk for creating MCP Servers with north
