API Reference¶

Configuration for the @guard decorator.

Attributes:

__post_init__() -> None

validate() -> None

Result from tool access evaluation.

Attributes:

Bases: CapiscioMCPError

Raised when tool access is denied by the guard.

Per RFC-006, all denials include: - reason: Specific denial reason code - detail: Human-readable explanation - evidence_id: ID of the evidence record for audit

Configuration for server identity verification.

Attributes:

Result of server identity verification.

Attributes:

is_verified: bool

has_identity: bool

Bases: str, Enum

Tool access decision result.

Per RFC-006 §6.3, every tool invocation attempt results in one of: - ALLOW: Tool execution is permitted - DENY: Tool execution is blocked with a reason

Bases: str, Enum

Caller authentication assurance level.

Per RFC-006 §5, every evidence log records the authentication method: - ANONYMOUS: No identity material provided - API_KEY: API key authentication (reduced assurance) - BADGE: CapiscIO Trust Badge authentication (full assurance)

Bases: str, Enum

Reason for denying tool access.

Per RFC-006 §6.4, denial must include a specific reason code.

Bases: str, Enum

Server identity verification state.

Per RFC-007 §5.2, clients classify servers into three states:

• VERIFIED_PRINCIPAL: Server badge verified, trust level established. The server has disclosed a DID and a valid badge signed by a trusted issuer.

• DECLARED_PRINCIPAL: Server DID disclosed but badge missing or invalid. Identity is claimed but not cryptographically verified.

• UNVERIFIED_ORIGIN: Server did not disclose any identity material. This is distinct from Trust Level 0 (self-signed) - UNVERIFIED_ORIGIN means NO identity was disclosed at all.

Bases: str, Enum

Server identity verification error codes.

Per RFC-007 §8, verification failures include specific error codes.

Bases: Exception

Error during server identity registration.

Bases: Exception

Error generating keypair.

Configuration for the @guard decorator.

Attributes:

__post_init__() -> None

validate() -> None

Result from tool access evaluation.

Attributes:

Configuration for server identity verification.

Attributes:

Result of server identity verification.

Attributes:

is_verified: bool

has_identity: bool

PoP request sent by client in initialize request _meta.

Per RFC-007, the client generates a random nonce and includes it in the initialize request. The server must sign this nonce to prove possession of the DID key.

Attributes:

created_datetime: datetime

to_meta() -> Dict[str, Any]

from_meta(
    meta: Optional[Dict[str, Any]],
) -> Optional["PoPRequest"]

is_expired(max_age: float = POP_MAX_AGE_SECONDS) -> bool

PoP response sent by server in initialize response _meta.

Per RFC-007, the server signs the client's nonce with its DID key and returns the signature. The client verifies this signature to prove the server controls the private key for the disclosed DID.

Attributes:

signed_datetime: datetime

to_meta() -> Dict[str, Any]

from_meta(
    meta: Optional[Dict[str, Any]],
) -> Optional["PoPResponse"]

Bases: Exception

Base exception for PoP errors.

Bases: PoPError

Error signing or verifying PoP.

Bases: PoPError

PoP request has expired.

Bases: str, Enum

Tool access decision result.

Per RFC-006 §6.3, every tool invocation attempt results in one of: - ALLOW: Tool execution is permitted - DENY: Tool execution is blocked with a reason

Bases: str, Enum

Caller authentication assurance level.

Per RFC-006 §5, every evidence log records the authentication method: - ANONYMOUS: No identity material provided - API_KEY: API key authentication (reduced assurance) - BADGE: CapiscIO Trust Badge authentication (full assurance)

Bases: str, Enum

Reason for denying tool access.

Per RFC-006 §6.4, denial must include a specific reason code.

Bases: str, Enum

Server identity verification state.

Per RFC-007 §5.2, clients classify servers into three states:

• VERIFIED_PRINCIPAL: Server badge verified, trust level established. The server has disclosed a DID and a valid badge signed by a trusted issuer.

• DECLARED_PRINCIPAL: Server DID disclosed but badge missing or invalid. Identity is claimed but not cryptographically verified.

• UNVERIFIED_ORIGIN: Server did not disclose any identity material. This is distinct from Trust Level 0 (self-signed) - UNVERIFIED_ORIGIN means NO identity was disclosed at all.

Bases: str, Enum

Server identity verification error codes.

Per RFC-007 §8, verification failures include specific error codes.

Bases: IntEnum

Trust levels per RFC-002 v1.4.

• LEVEL_0: Self-Signed (SS) - did:key issuer, no external validation
• LEVEL_1: Registered (REG) - Account registration with CapiscIO Registry
• LEVEL_2: Domain Validated (DV) - DNS/HTTP challenge proving domain control
• LEVEL_3: Organization Validated (OV) - DUNS/legal entity verification
• LEVEL_4: Extended Validated (EV) - Manual review + legal agreement

See: https://docs.capisc.io/rfcs/002-trust-badge/#5-trust-levels

Caller credential for tool access evaluation.

Only one of badge_jws or api_key should be set. If neither is set, the caller is treated as anonymous.

auth_level: AuthLevel

Bases: CapiscioMCPError

Raised when tool access is denied by the guard.

Per RFC-006, all denials include: - reason: Specific denial reason code - detail: Human-readable explanation - evidence_id: ID of the evidence record for audit

Bases: CapiscioMCPError

Raised when guard configuration is invalid.

This includes: - Invalid trust level values - Invalid tool name patterns - Conflicting configuration options

Bases: CapiscioMCPError

Raised when server identity verification fails.

Per RFC-007, verification can fail for various reasons including: - Invalid DID format - Badge verification failure - Origin/path binding mismatch - Trust level insufficient

Bases: CapiscioMCPError

Raised when connection to capiscio-core fails.

This includes: - Binary download failures - Process startup failures - gRPC connection failures - Health check failures

Bases: CapiscioMCPError

Raised when capiscio-core version is incompatible.

capiscio-mcp requires a specific range of capiscio-core versions. This error indicates the connected core is outside that range.

Bases: Exception

Error during server identity registration.

Bases: Exception

Error generating keypair.

MCP Server with CapiscIO identity disclosure, PoP signing, and tool guarding.

This class wraps FastMCP to:

1. Automatically inject server identity (DID, badge) into the _meta field of MCP initialize responses (RFC-007 §6.2).
2. Sign PoP challenges from clients to prove key ownership (RFC-007).
3. Guard registered tools with trust-level requirements (RFC-006).

The _meta injection works by patching mcp.server.session.ServerSession._received_request once (globally, idempotently) at server start-time. A per-invocation contextvar carries the meta dict so that only this server's responses are affected.

Example::

from capiscio_mcp import MCPServerIdentity
from capiscio_mcp.integrations.mcp import CapiscioMCPServer

identity = await MCPServerIdentity.connect(
    server_id=os.environ["CAPISCIO_SERVER_ID"],
    api_key=os.environ["CAPISCIO_API_KEY"],
)

server = CapiscioMCPServer(identity=identity)

@server.tool(min_trust_level=2)
async def read_file(path: str) -> str:
    with open(path) as f:
        return f.read()

server.run()

You can also supply credentials directly (without MCPServerIdentity)::

server = CapiscioMCPServer(
    name="filesystem",
    did="did:web:mcp.example.com:servers:filesystem",
    badge=os.environ.get("SERVER_BADGE"),
    private_key_path="/path/to/server.key.pem",
)

pop_enabled: bool

server: 'FastMCP'

identity_meta: Dict[str, str]

__init__(
    name: Optional[str] = None,
    did: Optional[str] = None,
    badge: Optional[str] = None,
    default_min_trust_level: int = 0,
    version: str = "1.0.0",
    private_key: Optional["Ed25519PrivateKey"] = None,
    private_key_path: Optional[str] = None,
    private_key_pem: Optional[Union[str, bytes]] = None,
    key_id: Optional[str] = None,
    identity: Optional[Any] = None,
) -> None

create_initialize_response_meta(
    request_meta: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]

tool(
    name: Optional[str] = None,
    description: Optional[str] = None,
    min_trust_level: Optional[int] = None,
    config: Optional[GuardConfig] = None,
) -> Callable[
    [Callable[..., Coroutine[Any, Any, T]]],
    Callable[..., Coroutine[Any, Any, T]],
]

@server.tool(min_trust_level=2)
async def execute_query(sql: str) -> list[dict]:
    ...

run(transport: str = 'stdio') -> None

run_stdio() -> None

run_sse(port: int = 8080) -> None

MCP Client with automatic server identity and PoP verification.

On connection this client:

1. Calls session.initialize() to get the MCP InitializeResult.
2. Extracts capiscio_server_did and capiscio_server_badge from result.meta (the _meta dict in the JSON response).
3. Calls :func:~capiscio_mcp.server.verify_server with those values.
4. Enforces min_trust_level and fail_on_unverified constraints.

Example::

async with CapiscioMCPClient(
    command="python server/main.py",
    badge=agent.badge,
    min_trust_level=1,
    fail_on_unverified=True,
) as client:
    print(f"Server verified at level {client.server_trust_level}")
    files = await client.call_tool("list_files", {"directory": "/tmp"})

For stdio transport (subprocess server)::

async with CapiscioMCPClient(
    command="python",
    args=["my_mcp_server.py"],
    min_trust_level=1,
) as client:
    result = await client.call_tool("my_tool", {"arg": "value"})

pop_verified: bool

server_state: Optional[ServerState]

server_trust_level: Optional[int]

server_did: Optional[str]

is_verified: bool

__init__(
    server_url: Optional[str] = None,
    command: Optional[str] = None,
    args: Optional[List[str]] = None,
    min_trust_level: int = 0,
    fail_on_unverified: bool = True,
    require_pop: bool = False,
    verify_config: Optional[VerifyConfig] = None,
    badge: Optional[str] = None,
    api_key: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
) -> None

create_initialize_request_meta() -> Dict[str, Any]

verify_initialize_response(
    response_meta: Optional[Dict[str, Any]],
    server_public_key: Optional["Ed25519PublicKey"] = None,
) -> bool

connect() -> None

close() -> None

call_tool(
    name: str, arguments: Optional[Dict[str, Any]] = None
) -> Any

list_tools() -> List[Dict[str, Any]]