spix_billing_credits

Check available credit balance for AI agent phone and communication services to monitor usage and manage costs.

Instructions

Show credit balance

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/spix_mcp/registry.py:626-634 (registration)

The "spix_billing_credits" tool is registered here in the COMMAND_REGISTRY as "billing.credits". It is automatically exposed as an MCP tool by the system based on mcp_expose="tool".

CommandSchema(
    path="billing.credits",
    cli_usage="spix billing credits",
    http_method="GET",
    api_endpoint="/billing/credits",
    mcp_expose="tool",
    mcp_profile="safe",
    description="Show credit balance",
),

src/spix_mcp/tools.py:94-203 (handler)

This function handles the execution for all MCP tools, including "spix_billing_credits". It resolves the tool name to a schema, validates the request, and dispatches it to the appropriate backend API endpoint.

async def create_tool_handler(
    session: McpSessionContext,
    tool_name: str,
    arguments: dict,
) -> list:
    """Execute an MCP tool call by dispatching to the backend API.

    This function:
    1. Resolves the tool name to a command schema
    2. Validates session scope (playbook access, channel access)
    3. Builds the API request
    4. Dispatches to the backend
    5. Returns the response as MCP TextContent

    Args:
        session: The MCP session context for scope validation.
        tool_name: The MCP tool name (e.g., "spix_playbook_create").
        arguments: The tool arguments from the MCP client.

    Returns:
        List containing a single TextContent with the JSON response.
    """
    # Import here to avoid circular imports and handle missing mcp package
    try:
        from mcp.types import TextContent
    except ImportError:
        # Fallback for when mcp is not installed
        class TextContent:  # type: ignore[no-redef]
            def __init__(self, type: str, text: str) -> None:
                self.type = type
                self.text = text

    # Resolve tool name to schema
    schema = get_schema_by_tool_name(tool_name)
    if not schema:
        return [
            TextContent(
                type="text",
                text=orjson.dumps(
                    {"ok": False, "error": {"code": "unknown_tool", "message": f"Unknown tool: {tool_name}"}}
                ).decode(),
            )
        ]

    # Validate tool access (not disabled)
    try:
        session.validate_tool_access(schema.path)
    except Exception as e:
        from spix_mcp.session import McpScopeError

        if isinstance(e, McpScopeError):
            return [TextContent(type="text", text=orjson.dumps({"ok": False, "error": e.to_dict()}).decode())]
        raise

    # Validate channel access if applicable
    channel = infer_channel_from_tool(schema.path)
    if channel:
        try:
            session.validate_channel_access(channel)
        except Exception as e:
            from spix_mcp.session import McpScopeError

            if isinstance(e, McpScopeError):
                return [TextContent(type="text", text=orjson.dumps({"ok": False, "error": e.to_dict()}).decode())]
            raise

    # Handle playbook_id: validate and apply default
    playbook_id = arguments.get("playbook_id")
    try:
        effective_playbook = session.validate_playbook_access(playbook_id)
        if effective_playbook and not playbook_id:
            # Apply default playbook
            arguments["playbook_id"] = effective_playbook
    except Exception as e:
        from spix_mcp.session import McpScopeError

        if isinstance(e, McpScopeError):
            return [TextContent(type="text", text=orjson.dumps({"ok": False, "error": e.to_dict()}).decode())]
        raise

    # Build endpoint URL with path parameters
    endpoint, remaining_args = build_endpoint_url(schema, arguments)

    # Dispatch to backend API
    client = session.client
    method = schema.http_method.lower()

    if method == "get":
        response = await asyncio.to_thread(client.get, endpoint, params=remaining_args if remaining_args else None)
    elif method == "post":
        response = await asyncio.to_thread(client.post, endpoint, json=remaining_args if remaining_args else None)
    elif method == "patch":
        response = await asyncio.to_thread(client.patch, endpoint, json=remaining_args if remaining_args else None)
    elif method == "delete":
        response = await asyncio.to_thread(client.delete, endpoint, params=remaining_args if remaining_args else None)
    else:
        response = await asyncio.to_thread(client.get, endpoint)

    # Build response envelope
    envelope: dict = {"ok": response.ok, "meta": response.meta}
    if response.ok:
        envelope["data"] = response.data
        if response.pagination:
            envelope["pagination"] = response.pagination
        if response.warnings:
            envelope["warnings"] = response.warnings
    else:
        envelope["error"] = response.error

    return [TextContent(type="text", text=orjson.dumps(envelope).decode())]

Spix