civic-mcp-client 0.1.0

Python client library for connecting to the Civic MCP Hub.

Civic MCP Client

Python client library for connecting to the Civic MCP Hub with direct bearer token auth or RFC 8693 token exchange.

Install

uv sync

Install optional integration extras:

uv sync --extra pydanticai --extra langchain --extra fastmcp

Quick Start

from civic_mcp_client import CivicMCPClient

client = CivicMCPClient(
    auth={"token": "your-civic-access-token"},
    civic_profile="7c9e6679-7425-40de-944b-e07fc1f90ae7",
)

tools = await client.get_tools()
instructions = await client.get_server_instructions()
result = await client.call_tool(name="tool-name", args={"foo": "bar"})

await client.close()

Token Exchange (RFC 8693)

import os
from civic_mcp_client import CivicMCPClient

client = CivicMCPClient(
    auth={
        "token_exchange": {
            "client_id": os.environ["CIVIC_CLIENT_ID"],
            "client_secret": os.environ["CIVIC_CLIENT_SECRET"],
            "subject_token": lambda: "external-token",
            "expires_in": 3600,  # optional requested lifetime in seconds
        }
    },
    civic_profile="7c9e6679-7425-40de-944b-e07fc1f90ae7",
)

The token exchange manager provides:

• cache + expiry handling
• token change detection
• in-flight deduplication for concurrent calls
• expiry buffer of min(30s, expires_in / 2)

Current access token can be retrieved via:

token = await client.get_access_token()

Testing

uv run --extra test python -m pytest
uv run --extra test python -m pytest -m integration

Manual Test Examples

Runnable scripts are available in examples/.

uv run python examples/direct_token.py
uv run python examples/token_exchange.py
uv run python examples/langchain_adapter.py
uv run python examples/pydanticai_adapter.py
uv run python examples/fastmcp_backend.py

To load environment variables from a .env file:

uv sync --extra examples
cp .env.example .env
uv run python -m dotenv run -- python examples/direct_token.py

Or, if you prefer running from inside the examples/ directory:

cd examples
cp ../.env.example .env
uv run python -m dotenv run -- python direct_token.py

Library Integrations

Use await client.adapt_for(...) with the adapter for your framework. It returns either a new CivicMCPClient (for backend adapters like FastMCP) or adapter-native tool output (e.g. list of schemas or tool definitions).

PydanticAI

from civic_mcp_client import CivicMCPClient
from civic_mcp_client.adapters.pydanticai import pydanticai

client = CivicMCPClient(auth={"token": "your-civic-access-token"})
tools = await client.adapt_for(pydanticai())

LangChain

from civic_mcp_client import CivicMCPClient
from civic_mcp_client.adapters.langchain import execute_langchain_tool_call, langchain

client = CivicMCPClient(auth={"token": "your-civic-access-token"})
tool_schemas = await client.adapt_for(langchain())

# model = model.bind_tools(tool_schemas)
# response = model.invoke("...")
# tool_result = await execute_langchain_tool_call(client, response.tool_calls[0])

FastMCP

from civic_mcp_client import CivicMCPClient
from civic_mcp_client.adapters.fastmcp import fastmcp

client = CivicMCPClient(
    auth={"token": "your-civic-access-token"},
    civic_profile="optional-profile-id",
)

fastmcp_client = await client.adapt_for(fastmcp())
# fastmcp_client is a CivicMCPClient with FastMCP backend; auth/headers come from config
tools = await fastmcp_client.get_tools()

Interface Notes

• civic_account was removed from Python client config to match the updated TypeScript direction.
• civic_profile remains supported and maps to x-civic-profile-id.
• TokenExchangeConfig supports expires_in and lock_to_profile (account lock removed).