Skip to main content

​
Overview

civic-mcp-client is a Python MCP client for connecting to the Civic MCP Hub and exposing MCP tools to AI frameworks. It supports:
  • Direct Civic token authentication
  • RFC 8693 token exchange (server-side only)
  • Adapter-based integration with frameworks like LangChain, Pydantic AI, and FastMCP
Start with the reference implementation: That demo uses Civic Auth in the frontend and forwards the authenticated Civic access token to a Python backend, which then passes it into CivicMCPClient(auth={"token": ...}).

​
Install

pip install civic-mcp-client
Optional framework integrations: 
pip install "civic-mcp-client[langchain,pydanticai,fastmcp]"

​
Authentication

​
Civic Token (direct; manual token for local testing)

​
Generate a Civic Token

  1. Log in to app.civic.com
  2. Click your account name in the bottom left
  3. Go to Install → MCP URL
  4. Click Generate Token and copy it immediately — it won’t be shown again
Never commit your token to source control. Store it in environment variables or a secrets manager. Tokens expire after 30 days.

​
Set Environment Variables

CIVIC_TOKEN=your-civic-token-here
CIVIC_URL=https://app.civic.com/hub/mcp
For production agents, lock to a specific toolkit by appending a profile parameter: 
CIVIC_URL=https://app.civic.com/hub/mcp?profile=your-toolkit-alias

​
Use the Token

Pass the token as a Bearer token in the Authorization header: 
headers = {"Authorization": f"Bearer {os.environ['CIVIC_TOKEN']}"}

headers: { Authorization: `Bearer ${process.env.CIVIC_TOKEN}` }

Full credentials guide

Token generation, URL parameters, OAuth vs token comparison
CIVIC_TOKEN (docs) is the same value as access_token. In the python-civic-mcp-client repo, this value is named CIVIC_ACCESS_TOKEN. 
# .env
CIVIC_TOKEN=your-civic-token-here

# Optional: lock tool access to a specific profile id
CIVIC_PROFILE_ID=optional-profile-id

from civic_mcp_client import CivicMCPClient

client = CivicMCPClient(
    # Use your token loading approach (env vars, secrets manager, etc.)
    auth={"token": "your-civic-token-here"},
    civic_profile="optional-profile-id",
)

​
Token Exchange (RFC 8693)

Token exchange is server-side only. Your Civic client secret must never be shipped to a browser or untrusted environment. 
# .env (server)
CIVIC_CLIENT_ID=your_client_id
CIVIC_CLIENT_SECRET=your_client_secret

# Optional: lock tool access to a specific profile id
CIVIC_PROFILE_ID=optional-profile-id

from civic_mcp_client import CivicMCPClient

def get_external_access_token() -> str:
    # Replace this with your IdP / external provider token fetch.
    return "external-token"

client = CivicMCPClient(
    auth={
        "token_exchange": {
            # Token exchange credentials (server-side only)
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "subject_token": get_external_access_token,
            "expires_in": 3600,  # optional requested lifetime in seconds
        }
    },
    civic_profile="optional-profile-id",
)

​
Quick Start (manual token)

This quick start uses a manually generated Civic access token for local testing. For a production-like frontend + Python backend setup, use the demo app above. 
import asyncio
from civic_mcp_client import CivicMCPClient


async def main() -> None:
    client = CivicMCPClient(
        auth={"token": "your-civic-token-here"},
        civic_profile="optional-profile-id",
    )

    # Discover available tools from your configured toolkit
    tools = await client.get_tools()

    # Call a specific tool directly
    result = await client.call_tool(
        name="tool-name",
        args={"foo": "bar"},
    )

    print("Tools loaded:", len(tools))
    print("Tool call result:", result)

    await client.close()


asyncio.run(main())

​
Framework Adapters

Use await client.adapt_for(...) with the adapter for your framework. Depending on the adapter, adapt_for(...) will either:
  • Return a new CivicMCPClient (backend adapters like FastMCP), or
  • Return adapter-native tool outputs (e.g. tool schemas / definitions)

​
LangChain / LangGraph

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())

​
Pydantic AI

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

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

​
FastMCP

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

client = CivicMCPClient(auth={"token": "your-civic-access-token"})

fastmcp_client = await client.adapt_for(fastmcp())
tools = await fastmcp_client.get_tools()

​
Next Steps

  • See the agent deployment guide: profile locking, URL parameters, and best practices

​
Get help

  • Ask questions in our developer Slack