> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 03.5 mcp

# MCP

BindAI provides a lightweight HTTP-based MCP integration package for discovering and invoking external tools.

The current implementation is intentionally small and focused on connecting BindAI's tool system to an HTTP service that exposes a simple tool-discovery and tool-invocation interface.

It should be understood as a **lightweight HTTP bridge**, not as a complete implementation of the Model Context Protocol.

***

# Current MCP Scope

The `bindai-mcp` package currently provides:

* `MCPClient`
* `MCPTool`
* HTTP-based tool discovery
* HTTP-based tool invocation
* Tool metadata and schema mapping
* Integration with the BindAI tool abstraction

The current implementation does **not** attempt to implement the complete MCP protocol.

The package provides a practical integration boundary for external tools while keeping the external HTTP communication behind the BindAI tool abstraction.

***

# MCP Package

The package is:

```text theme={null}
bindai-mcp
```

Its public API currently exposes:

```python theme={null}
from bindai_mcp import MCPClient, MCPTool
```

The package currently depends on:

```text theme={null}
httpx
bindai-tool
```

The package itself declares:

```text theme={null}
Python >= 3.11
```

***

# Architecture

The current implementation can be understood as:

```text theme={null}
BindAI Agent
      |
      v
BindAI Tool System
      |
      v
MCPTool
      |
      v
MCPClient
      |
      | HTTP
      v
External HTTP Tool Service
```

The external service exposes tools through a small HTTP interface.

`MCPClient` discovers those tools and creates `MCPTool` instances that can participate in the BindAI tool system.

***

# MCPClient

`MCPClient` is the client used to communicate with the external HTTP tool service.

Create a client with the service URL:

```python theme={null}
from bindai_mcp import MCPClient

client = MCPClient("http://localhost:8000")
```

The client currently stores the configured URL and provides asynchronous tool discovery through:

```python theme={null}
tools = await client.list_tools()
```

The client does not currently provide explicit `connect()` or `disconnect()` methods.

It also does not maintain a persistent MCP session.

***

# Tool Discovery

Tool discovery is performed with:

```python theme={null}
await client.list_tools()
```

The current implementation sends:

```text theme={null}
GET {server_url}/tools
```

For example:

```text theme={null}
GET http://localhost:8000/tools
```

The response is expected to contain a JSON list of tool definitions.

A conceptual response is:

```json theme={null}
[
  {
    "name": "search",
    "description": "Search documents",
    "schema": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        }
      }
    }
  }
]
```

Each returned item is converted into an `MCPTool`.

***

# Tool Metadata

An externally discovered tool can provide:

* `name`
* `description`
* `schema`

The schema is optional.

If no description is provided, the implementation uses an empty string.

If no schema is provided, the implementation uses an empty dictionary.

For example:

```json theme={null}
{
  "name": "search",
  "description": "Search documents",
  "schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      }
    }
  }
}
```

The resulting BindAI tool exposes the same metadata through its tool definition.

***

# MCPTool

`MCPTool` is the BindAI `Tool` implementation created for each discovered external tool.

Its public properties include:

```python theme={null}
tool.name
tool.description
tool.definition
```

The tool definition contains:

* tool name
* tool description
* parameter schema

For example:

```python theme={null}
tool.definition
```

produces a BindAI `ToolDefinition` containing the discovered metadata.

This allows an external HTTP tool to participate in BindAI's existing tool abstraction.

***

# Tool Invocation

When an `MCPTool` is executed, the current implementation sends:

```text theme={null}
POST {server_url}/call
```

For example:

```text theme={null}
POST http://localhost:8000/call
```

The JSON request body has the following structure:

```json theme={null}
{
  "tool": "search",
  "arguments": {
    "query": "BindAI"
  }
}
```

The `tool` field contains the name of the discovered tool.

The `arguments` field contains the arguments supplied by the BindAI execution context.

***

# Tool Arguments

When an `MCPTool` receives an execution context containing `variables`, those variables are used as the tool arguments.

For example:

```python theme={null}
context.variables = {
    "query": "BindAI"
}
```

results in a request equivalent to:

```json theme={null}
{
  "tool": "search",
  "arguments": {
    "query": "BindAI"
  }
}
```

If the execution context does not provide `variables`, the implementation uses an empty argument dictionary.

The current MCP implementation does not perform additional argument transformation or validation beyond the behavior provided by the underlying BindAI tool definition and external service.

***

# Tool Results

After invoking the external service, the response body is parsed as JSON.

The JSON response is returned through BindAI's `ToolResult`:

```python theme={null}
ToolResult(
    success=True,
    output=response.json(),
)
```

For example, if the external service returns:

```json theme={null}
{
  "results": [
    "BindAI documentation"
  ]
}
```

the BindAI tool result contains that object as its output.

***

# HTTP Errors

The current implementation calls:

```python theme={null}
response.raise_for_status()
```

for HTTP requests.

Therefore, HTTP error responses result in an exception rather than being converted into a successful `ToolResult`.

Applications should handle these failures at the appropriate application or agent boundary.

A conceptual flow is:

```text theme={null}
BindAI Tool
     |
     v
HTTP Request
     |
     +---- 2xx ---> JSON Tool Result
     |
     +---- HTTP Error ---> Exception
```

***

# MCP and BindAI Tools

The main purpose of the package is to bridge external HTTP tools into the BindAI tool system.

The relationship is:

```text theme={null}
                  BindAI Tool System
                         |
              +----------+----------+
              |                     |
              v                     v
        Local Python Tool       MCPTool
              |                     |
              v                     v
        Application Code      External HTTP Service
```

This allows an application to combine locally implemented tools with tools exposed by an external service.

The agent can interact with the resulting tools through BindAI's normal tool abstraction.

***

# MCP and Agents

An application can expose discovered `MCPTool` instances to an agent using the normal BindAI tool mechanisms.

The conceptual flow is:

```text theme={null}
MCPClient
    |
    | list_tools()
    v
MCPTool instances
    |
    v
BindAI Tool Registry / Agent
    |
    v
Tool Selection
    |
    v
MCPTool.execute()
    |
    v
External HTTP Service
```

The agent does not need to implement the external service's HTTP request format directly.

The MCP integration keeps that communication inside the tool implementation.

***

# MCP and Workflows

MCP tools can participate in workflows when they are exposed through BindAI's normal tool system.

For example:

```text theme={null}
Workflow
    |
    v
Agent
    |
    v
MCPTool
    |
    v
External HTTP Service
```

The workflow remains responsible for orchestration.

The MCP package provides the external tool boundary.

Features such as conditions, loops, parallel execution, retries, timeouts, and human tasks belong to the corresponding BindAI workflow or automation systems rather than to `bindai-mcp` itself.

***

# MCP and Automation

The `bindai-mcp` package does not currently provide its own automation or event-trigger integration.

MCP tools may still be used by applications that also use BindAI automation and event infrastructure, provided the tools are registered through the normal BindAI mechanisms.

For example:

```text theme={null}
Automation
    |
    v
BindAI Application
    |
    v
Agent / Tool Execution
    |
    v
MCPTool
    |
    v
External HTTP Service
```

The automation layer and MCP layer remain separate responsibilities.

***

# Observability

The `bindai-mcp` package does not currently provide a dedicated MCP observability system.

It also does not itself expose MCP-specific event types or an MCP event recorder.

Applications can still observe MCP-backed tool execution through whatever logging, instrumentation, or execution observability they apply around the BindAI tool and agent layers.

BindAI's broader runtime observability facilities can therefore be used at the application level without implying that the MCP package itself implements tracing or monitoring.

***

# Configuration

The current `MCPClient` requires only a URL:

```python theme={null}
client = MCPClient("http://localhost:8000")
```

The package does not define a dedicated MCP configuration file format.

It also does not define built-in environment variables such as:

```text theme={null}
MCP_SERVER_URL
MCP_API_KEY
```

Applications are free to obtain the URL and any required credentials from their own configuration system.

For example:

```python theme={null}
import os

from bindai_mcp import MCPClient

client = MCPClient(
    os.environ["MCP_SERVER_URL"]
)
```

The exact configuration mechanism is an application concern.

***

# Authentication

The current `MCPClient` implementation does not provide a built-in authentication mechanism.

In particular, the current client does not expose configuration for:

* API keys
* Bearer tokens
* OAuth
* client certificates
* custom authentication headers

If the external service requires authentication, the application must provide an appropriate integration mechanism or extend the client implementation.

Do not assume that an MCP service is authenticated simply because it is reachable over HTTP.

***

# Security

MCP-backed tools can provide access to external systems and should therefore be treated as security-sensitive application components.

Applications should consider:

* Authentication
* Authorization
* TLS
* Network restrictions
* Input validation
* External service permissions
* Tool permissions
* Secret management
* Logging of sensitive information

The current `bindai-mcp` client does not implement these concerns itself.

Do not expose sensitive external operations to agents unless the application intentionally allows them.

***

# Tool Permissions

External services may expose tools that perform different levels of access.

For example:

```text theme={null}
External Service
    |
    +---- Read Data
    |
    +---- Search Data
    |
    +---- Update Data
    |
    +---- Delete Data
```

Applications should decide which discovered tools are appropriate for each agent.

Avoid automatically exposing sensitive or destructive operations to every agent.

Use the principle of least privilege when deciding which external tools an agent can invoke.

***

# Timeouts and Reliability

The current `MCPClient` does not expose a configurable timeout parameter.

The underlying HTTP behavior is provided by `httpx`.

Applications that require strict timeout, retry, circuit-breaker, or resilience policies should account for this at the application or integration layer.

External HTTP services can fail because of:

* Network problems
* Service outages
* Invalid requests
* Authentication failures
* HTTP errors
* Unexpected responses
* Latency or timeout conditions

Treat MCP-backed tools as external dependencies.

***

# Testing

The `bindai-mcp` package includes tests for its core behavior.

The current test coverage verifies:

* Tool discovery
* Tool metadata
* Tool schema mapping
* BindAI `ToolDefinition` generation
* Tool invocation
* Tool argument forwarding
* Tool result handling

The discovery test verifies that a response from:

```text theme={null}
GET /tools
```

is converted into `MCPTool` instances.

The invocation test verifies that:

```text theme={null}
POST /call
```

receives the expected tool name and arguments.

A representative test boundary is:

```text theme={null}
Test
 |
 v
MCPClient / MCPTool
 |
 v
Mock HTTP Client
 |
 v
Expected Tool Metadata / Result
```

The current tests mock the HTTP layer rather than contacting a production MCP service.

***

# Example Test Contract

A discovered tool can look like:

```json theme={null}
{
  "name": "search",
  "description": "Search documents",
  "schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      }
    }
  }
}
```

The resulting tool should expose:

```python theme={null}
tool.name
# "search"

tool.description
# "Search documents"

tool.schema
# {
#     "type": "object",
#     "properties": {
#         "query": {"type": "string"}
#     }
# }
```

When executed with:

```python theme={null}
context.variables = {
    "query": "BindAI"
}
```

the external service should receive:

```json theme={null}
{
  "tool": "search",
  "arguments": {
    "query": "BindAI"
  }
}
```

***

# HTTP Bridge Contract

The current bridge has two core endpoints.

## Tool discovery

```text theme={null}
GET /tools
```

Expected response:

```json theme={null}
[
  {
    "name": "tool-name",
    "description": "Tool description",
    "schema": {}
  }
]
```

## Tool invocation

```text theme={null}
POST /call
```

Expected request:

```json theme={null}
{
  "tool": "tool-name",
  "arguments": {}
}
```

Expected response:

```json theme={null}
{
  "result": "..."
}
```

The exact response payload is not transformed into a special MCP response structure. The JSON returned by the external service becomes the `output` of the BindAI `ToolResult`.

***

# Example Usage

A minimal application can discover external tools with:

```python theme={null}
import asyncio

from bindai_mcp import MCPClient


async def main():
    client = MCPClient("http://localhost:8000")

    tools = await client.list_tools()

    for tool in tools:
        print(tool.name)
        print(tool.description)
        print(tool.definition)


asyncio.run(main())
```

The discovered tools can then be integrated with the application's normal BindAI tool configuration.

***

# Docker

The MCP package itself does not start an HTTP server.

It is a client-side integration package that communicates with an already-running HTTP service.

When BindAI runs inside Docker, the configured MCP service must be reachable from the container.

For example:

```text theme={null}
BindAI Container
       |
       | HTTP
       v
MCP HTTP Service
```

If the external service runs in another Docker container, the containers must be able to communicate over the appropriate Docker network.

If the service is external, the BindAI container needs appropriate outbound network access.

***

# Docker Compose

A Docker Compose deployment can include a BindAI application and an external HTTP tool service:

```text theme={null}
Docker Compose

+--------------------+
| BindAI Application |
|                    |
| Agent              |
| Workflow           |
| MCPClient          |
+---------+----------+
          |
          | HTTP
          v
+--------------------+
| HTTP Tool Service  |
|                    |
| External Tools     |
+--------------------+
```

The exact service configuration depends on the external HTTP tool provider.

The `bindai-mcp` package itself does not provide a server container or Compose service.

***

# Current Limitations

The current implementation is intentionally lightweight.

It should **not** be described as a complete MCP protocol implementation.

The current package does not implement a complete MCP stack including features such as:

* Full protocol negotiation
* MCP session management
* MCP resources
* MCP prompts
* Multiple MCP transport implementations
* Standard MCP server implementation
* Built-in authentication
* OAuth flows
* MCP-specific tracing
* Full protocol compliance across MCP features

The current implementation is specifically centered on:

```text theme={null}
GET  /tools
POST /call
```

and the conversion of discovered external tools into BindAI `Tool` objects.

***

# MCP vs BindAI Connections

MCP and BindAI Connections provide different integration approaches.

| Capability                     | `bindai-mcp`            | BindAI Connections     |
| ------------------------------ | ----------------------- | ---------------------- |
| External tools                 | Yes                     | Depends on integration |
| Tool discovery                 | Yes                     | Depends on integration |
| HTTP communication             | Yes                     | Many integrations      |
| Generic external tool boundary | Yes                     | No                     |
| Dedicated service integration  | No                      | Yes                    |
| BindAI tool integration        | Yes                     | Depends on integration |
| Protocol implementation        | Lightweight HTTP bridge | BindAI-specific        |
| Service-specific operations    | No                      | Primary purpose        |

Use a BindAI Connection when BindAI provides a dedicated integration for the service.

Use `bindai-mcp` when the required capability is exposed through the compatible HTTP tool bridge.

***

# MCP vs Local Tools

Local tools execute application-defined Python code.

MCP tools represented by `MCPTool` forward execution to an external HTTP service.

Local tool:

```text theme={null}
Agent
  |
  v
BindAI Tool
  |
  v
Python Function
```

MCP-backed tool:

```text theme={null}
Agent
  |
  v
BindAI Tool
  |
  v
MCPTool
  |
  v
HTTP Service
```

Both can participate in the BindAI tool system.

The primary difference is where the actual operation executes.

***

# Recommended Project Structure

An application using the MCP bridge may keep MCP-related setup separate from agents and workflows:

```text theme={null}
my-ai-app/

├── agents/
├── tools/
├── workflows/
├── mcp/
│   └── clients.py
├── tests/
│   └── test_mcp.py
├── bindai.toml
├── main.py
└── .env
```

The exact project structure is application-specific.

The important principle is to keep external-service configuration and credentials separate from agent business logic.

***

# Production Considerations

When deploying an application that uses the MCP bridge, consider:

* External service availability
* Network connectivity
* Authentication requirements
* TLS
* Tool permissions
* Input validation
* HTTP failures
* Timeouts
* Retry policies
* Rate limits
* External service monitoring
* Secret management

The current MCP package is intentionally minimal, so production applications may need additional infrastructure around it.

A production application should define what happens when an external tool service becomes unavailable.

***

# Future MCP Capabilities

The MCP integration can be expanded in future releases.

Potential areas include:

* More complete MCP protocol support
* Standard MCP transports
* MCP resources
* MCP prompts
* Session management
* Authentication support
* Richer tool metadata
* Improved protocol compatibility
* MCP server functionality
* More advanced error and timeout handling
* Deeper observability integration

These capabilities should be introduced incrementally while preserving the existing BindAI tool abstraction where practical.

***

# Best Practices

* Treat external MCP-backed services as external dependencies.
* Keep MCP configuration separate from agent business logic.
* Never hard-code credentials.
* Use secure configuration and secret storage.
* Expose only the tools an agent actually needs.
* Follow least-privilege principles.
* Validate external tool inputs.
* Handle HTTP failures explicitly.
* Use appropriate timeout and retry strategies at the application level.
* Test MCP integrations independently.
* Do not assume authentication is provided by `bindai-mcp`.
* Do not assume MCP resources or prompts are supported.
* Do not assume session management is available.
* Do not describe the v0.1 implementation as full MCP protocol compliance.
* Verify the capabilities of the external HTTP service before depending on them.

***

# Summary

BindAI v0.1 provides a lightweight HTTP-based MCP integration through the `bindai-mcp` package.

The main flow is:

```text theme={null}
BindAI Agent
      |
      v
BindAI Tool System
      |
      v
MCPTool
      |
      v
MCPClient
      |
      | HTTP
      +---- GET /tools
      |
      +---- POST /call
      |
      v
External HTTP Tool Service
```

The current implementation provides:

* `MCPClient`
* `MCPTool`
* HTTP tool discovery
* HTTP tool invocation
* Tool metadata and schema mapping
* BindAI `Tool` integration
* JSON tool results

The current implementation is intentionally smaller than a complete MCP protocol stack.

For v0.1, the MCP layer should therefore be viewed as a **practical HTTP tool bridge and foundation for future MCP capabilities**, rather than as a full MCP implementation.

Applications that require specific MCP protocol features should verify that those features are supported before depending on them.