# Tooling & MCP Integration

> Extending agent capabilities via native Python functions and the Model Context Protocol (MCP) bridge for stdio and SSE servers.

- Repository: google-antigravity/antigravity-sdk-python
- GitHub: https://github.com/google-antigravity/antigravity-sdk-python
- Human wiki: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867
- Complete Markdown: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867/llms-full.txt

## Source Files

- `google/antigravity/tools/tool_runner.py`
- `google/antigravity/mcp/bridge.py`
- `google/antigravity/mcp/README.md`
- `examples/getting_started/custom_tools.py`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [google/antigravity/tools/tool_runner.py](google/antigravity/tools/tool_runner.py)
- [google/antigravity/mcp/bridge.py](google/antigravity/mcp/bridge.py)
- [google/antigravity/mcp/README.md](google/antigravity/mcp/README.md)
- [examples/getting_started/custom_tools.py](examples/getting_started/custom_tools.py)
- [google/antigravity/tools/tool_context.py](google/antigravity/tools/tool_context.py)
</details>

# Tooling & MCP Integration

The Antigravity SDK provides a robust and flexible system for extending agent capabilities through tools. Tools allow agents to perform actions, retrieve data, and interact with external systems. The SDK supports two primary methods for tool integration: native Python functions and the Model Context Protocol (MCP).

By using the `ToolRunner`, the SDK manages the registration, schema generation, and execution of tools, including automatic dependency injection for stateful operations. The `McpBridge` further extends this by allowing the agent to consume tools hosted on external MCP servers over various transport protocols.

## Tool Runner

The `ToolRunner` is the central registry and executor for all Python-based tools within the SDK. It maintains a mapping of tool names to their corresponding callables and handles the complexities of invoking them, whether they are synchronous or asynchronous.

Sources: [google/antigravity/tools/tool_runner.py:123-129]()

### Key Features
- **Sync and Async Support**: Tools can be defined as standard Python functions or `async` coroutines. Synchronous tools are automatically executed in a separate thread to avoid blocking the main event loop.
- **Concurrent Execution**: The `process_tool_calls` method allows for the parallel execution of multiple tool calls using `asyncio.gather`, improving performance during complex multi-tool reasoning steps.
- **Signature Proxying**: To ensure models only see relevant parameters, the `ToolRunner` uses `get_public_callable` to generate a proxy signature that hides internal-only parameters like `ToolContext`.

Sources: [google/antigravity/tools/tool_runner.py:221-230](), [google/antigravity/tools/tool_runner.py:276-294]()

## Native Python Tools

Native tools are Python callables registered directly with the agent. They are ideal for tight integration with local logic, database access, or existing Python libraries.

### Tool Context & State Management
Stateful tools can opt-in to receiving a `ToolContext` by declaring it as a typed parameter. The `ToolRunner` automatically injects this context at execution time.

Sources: [google/antigravity/tools/tool_context.py:42-51]()

The `ToolContext` provides:
- **State Persistence**: `get_state(key)` and `set_state(key, value)` allow tools to maintain information across multiple conversational turns.
- **Asynchronous Messaging**: The `send(message)` method allows tools to inject notifications or follow-up messages back into the conversation asynchronously.
- **Identity**: Access to the `conversation_id` for tracking and logging.

Sources: [google/antigravity/tools/tool_context.py:66-105]()

### Example: Stateful Fruit Tracker
```python
from google.antigravity import ToolContext

def record_fruit(sku: str, count: int, ctx: ToolContext) -> str:
    """Records the count of fruits by SKU."""
    current_counts = ctx.get_state("fruit_counts", {})
    current_counts[sku] = current_counts.get(sku, 0) + count
    ctx.set_state("fruit_counts", current_counts)
    
    return f"Recorded {count} units for {sku}. Total is {current_counts[sku]}."
```
Sources: [examples/getting_started/custom_tools.py:67-87]()

## MCP Integration

The Model Context Protocol (MCP) bridge allows the Antigravity SDK to connect to external tool providers. This enables the use of a wide ecosystem of pre-built tools without writing custom Python wrappers for every service.

Sources: [google/antigravity/mcp/README.md:1-15]()

### McpBridge
The `McpBridge` class manages the lifecycle of MCP client sessions. It discovers tools from connected servers and converts them into `ToolWithSchema` objects compatible with the `ToolRunner`.

Sources: [google/antigravity/mcp/bridge.py:59-69]()

### Supported Transports
| Transport Type | Description |
| :--- | :--- |
| **stdio** | Connects to local MCP servers running as subprocesses (e.g., via `npx`). |
| **SSE** | Connects to remote MCP servers using Server-Sent Events over HTTP. |
| **Streamable HTTP** | Advanced remote connection with fine-grained timeout and lifecycle management. |

Sources: [google/antigravity/mcp/bridge.py:80-91](), [google/antigravity/mcp/bridge.py:115-139]()

### Integration Architecture
The following diagram illustrates how the `McpBridge` interacts with the SDK's core tooling system:

```mermaid
graph TD
    Agent[Agent] --> TR[ToolRunner]
    TR --> NT[Native Python Tools]
    TR --> Bridge[McpBridge]
    Bridge --> Stdio[stdio Subprocess]
    Bridge --> SSE[SSE / HTTP Server]
    
    subgraph "External MCP Servers"
        Stdio
        SSE
    end
```

## Summary

The Antigravity SDK's tooling system provides a unified interface for both local Python execution and remote MCP-based capability extension. By centralizing tool management in the `ToolRunner` and providing a dedicated `McpBridge`, the SDK ensures that agents can seamlessly leverage a diverse set of tools while maintaining clean separation between tool implementation and agent logic.

Sources: [google/antigravity/tools/tool_runner.py:15-29]()