MCP Tools

SandBase provides 2000+ pre-built tools via the Model Context Protocol (MCP) that you can attach to your agents. Tools give agents the ability to interact with the real world — search the web, query databases, send emails, and more.

How It Works

User Message → Agent (LLM) → Tool Call Decision
                                    │
                                    ▼
                            ┌───────────────┐
                            │  MCP Server   │
                            │  (tool host)  │
                            └───────┬───────┘
                                    │
                                    ▼
                            Tool Execution
                                    │
                                    ▼
                            Result → Agent → Response

The agent's LLM decides when to call tools based on the user's request. SandBase handles the MCP protocol, tool execution, and result formatting automatically.

Attaching Tools to Agents

Using Platform Tools

SandBase hosts popular MCP servers that you can attach by name:

python

agent = requests.post(
    "https://api.sandbase.ai/default/v1/agents",
    headers={"Authorization": "Bearer sk-sb-YOUR_KEY"},
    json={
        "name": "Research Agent",
        "model": {"name": "claude-sonnet-4"},
        "system": "You are a research assistant. Use tools to find information.",
        "tools": [
            {"type": "mcp", "server": "web-search"},
            {"type": "mcp", "server": "web-fetch"},
            {"type": "mcp", "server": "wikipedia"},
        ]
    }
).json()

Using Custom MCP Servers

Connect your own MCP servers:

python

agent = requests.post(
    "https://api.sandbase.ai/default/v1/agents",
    headers={"Authorization": "Bearer sk-sb-YOUR_KEY"},
    json={
        "name": "Data Agent",
        "model": {"name": "gpt-4o"},
        "system": "You help users query their database.",
        "mcp_servers": [
            {
                "name": "my-database",
                "url": "https://your-server.com/mcp",
                "headers": {"X-API-Key": "your-key"}
            }
        ]
    }
).json()

Available Tool Categories

Web & Search

Tool Server	Tools	Description
`web-search`	`search`	Search the web via multiple engines
`web-fetch`	`fetch`, `screenshot`	Fetch web pages, take screenshots
`browser`	`navigate`, `click`, `type`, `screenshot`	Full browser automation (Playwright-based)
`wikipedia`	`search`, `get_article`	Wikipedia search and retrieval
`arxiv`	`search`, `get_paper`	Academic paper search
`news`	`search`, `trending`	Real-time news aggregation

Browser Automation

Tool Server	Tools	Description
`browser`	`navigate`, `click`, `type`, `screenshot`, `scroll`, `wait`	Full headless browser control
`scraper`	`extract`, `crawl`, `parse`	Structured data extraction from web pages
`pdf-reader`	`extract_text`, `extract_tables`	Parse PDF documents from URLs

Data & Databases

Tool Server	Tools	Description
`postgres`	`query`, `list_tables`, `describe`, `explain`	PostgreSQL database access
`mysql`	`query`, `list_tables`, `describe`	MySQL database access
`redis`	`get`, `set`, `del`, `keys`, `hget`, `hset`	Redis key-value and hash operations
`sqlite`	`query`, `execute`, `list_tables`	SQLite file-based database
`mongodb`	`find`, `insert`, `update`, `aggregate`	MongoDB document operations
`elasticsearch`	`search`, `index`, `bulk`	Elasticsearch full-text search
`supabase`	`query`, `insert`, `rpc`	Supabase Postgres + realtime

Code Execution

Tool Server	Tools	Description
`code-exec`	`run_python`, `run_javascript`, `run_typescript`	Execute code snippets in sandboxed environments
`jupyter`	`execute_cell`, `create_notebook`	Jupyter notebook operations
`shell`	`exec`, `background`, `kill`	Shell command execution
`docker`	`run`, `build`, `logs`	Docker container management

Version Control & DevOps

Tool Server	Tools	Description
`github`	`search_repos`, `get_file`, `create_issue`, `create_pr`, `list_commits`	GitHub API integration
`gitlab`	`search`, `get_file`, `create_issue`, `create_mr`	GitLab API integration
`git`	`clone`, `diff`, `commit`, `log`, `branch`	Git operations
`jira`	`search`, `create_issue`, `update_issue`, `transition`	Jira project management
`linear`	`create_issue`, `search`, `update`	Linear issue tracking

Communication

Tool Server	Tools	Description
`email`	`send`, `search`, `read`, `reply`	Email operations (SMTP/IMAP)
`slack`	`send_message`, `search`, `list_channels`, `react`	Slack workspace integration
`discord`	`send_message`, `read_messages`, `react`	Discord bot operations
`twilio`	`send_sms`, `make_call`	SMS and voice via Twilio
`telegram`	`send_message`, `get_updates`	Telegram bot API
`webhook`	`send`, `register`	Generic webhook dispatch

File & Storage

Tool Server	Tools	Description
`filesystem`	`read`, `write`, `list`, `delete`, `move`, `copy`	Local file operations
`s3`	`get`, `put`, `list`, `delete`, `presign`	AWS S3 operations
`google-drive`	`search`, `download`, `upload`, `share`	Google Drive access
`dropbox`	`upload`, `download`, `list`, `share`	Dropbox file storage
`gcs`	`get`, `put`, `list`, `delete`	Google Cloud Storage

AI & Generation

Tool Server	Tools	Description
`image-gen`	`generate`, `edit`, `variations`	AI image generation (DALL-E, Stable Diffusion)
`tts`	`synthesize`, `list_voices`	Text-to-speech synthesis
`transcription`	`transcribe`, `translate`	Audio transcription and translation
`embeddings`	`embed`, `similarity`	Vector embeddings and similarity search
`ocr`	`extract_text`, `extract_structured`	Optical character recognition

Analytics & Monitoring

Tool Server	Tools	Description
`google-analytics`	`query`, `report`	GA4 data retrieval
`posthog`	`query`, `capture`	Product analytics
`sentry`	`list_issues`, `get_issue`, `resolve`	Error tracking
`datadog`	`query_metrics`, `list_alerts`	Infrastructure monitoring

CRM & Business

Tool Server	Tools	Description
`hubspot`	`search_contacts`, `create_deal`, `update`	HubSpot CRM
`salesforce`	`query`, `create`, `update`	Salesforce SOQL and CRUD
`notion`	`search`, `create_page`, `update_page`, `query_database`	Notion workspace
`airtable`	`list_records`, `create`, `update`	Airtable base operations

Listing Available Tools

List All MCP Servers

bash

curl https://api.sandbase.ai/api/mcp/servers \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

List Tools for a Server

bash

curl https://api.sandbase.ai/api/mcp/web-search/tools \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Response:

json

{
  "tools": [
    {
      "name": "search",
      "description": "Search the web for information",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {"type": "string", "description": "Search query"},
          "limit": {"type": "integer", "default": 10}
        },
        "required": ["query"]
      }
    }
  ]
}

Tool Execution Flow

When an agent uses a tool, the flow is:

User sends message → Agent receives it
Agent decides → LLM outputs a tool call (based on system prompt + available tools)
SandBase executes → Calls the MCP server, gets the result
Agent continues → LLM receives tool result, generates final response

python

# This happens automatically — you just send messages
response = requests.post(
    f"https://api.sandbase.ai/default/v1/sessions/{session_id}/events",
    headers={"Authorization": "Bearer sk-sb-YOUR_KEY"},
    json={
        "type": "message",
        "role": "user",
        "content": "What's the weather in Tokyo today?"
    }
).json()

# Agent automatically called web-search, then responded
print(response["content"])
# "Based on my search, Tokyo is currently 22°C with partly cloudy skies..."

Custom Server Setup Guide

Beyond the 2000+ platform tools, you can connect your own MCP servers to give agents access to proprietary APIs, internal databases, or custom logic.

Self-Hosted Server Requirements

Your MCP server must:

Implement the MCP specification (SSE transport)
Be accessible via HTTPS from SandBase's infrastructure
Respond to tools/list and tools/call methods
Return results within 30 seconds (configurable timeout)

Connecting a Custom Server

python

import requests

agent = requests.post(
    "https://api.sandbase.ai/default/v1/agents",
    headers={"Authorization": "Bearer sk-sb-YOUR_KEY"},
    json={
        "name": "Internal Data Agent",
        "model": {"name": "claude-sonnet-4"},
        "system": "You help employees query internal systems.",
        "mcp_servers": [
            {
                "name": "internal-crm",
                "url": "https://mcp.yourcompany.com/crm",
                "headers": {
                    "Authorization": "Bearer your-internal-token",
                    "X-Team-ID": "engineering"
                },
                "timeout": 15000
            }
        ]
    }
).json()

Authentication Options

SandBase supports several authentication methods for custom servers:

Method	Configuration	Use Case
Bearer token	`"Authorization": "Bearer <token>"`	Most APIs
API key header	`"X-API-Key": "<key>"`	Simple key auth
Custom headers	Any header key-value pairs	Internal services
mTLS	`"tls": {"cert": "...", "key": "..."}`	Zero-trust environments

python

# Bearer token authentication
{
    "name": "my-server",
    "url": "https://mcp.example.com",
    "headers": {"Authorization": "Bearer sk-your-token"}
}

# API key authentication
{
    "name": "my-server",
    "url": "https://mcp.example.com",
    "headers": {"X-API-Key": "your-api-key"}
}

# Multiple custom headers
{
    "name": "my-server",
    "url": "https://mcp.internal.corp",
    "headers": {
        "X-API-Key": "key-123",
        "X-Org-ID": "org-456",
        "X-Environment": "production"
    }
}

Server Configuration Options

Option	Type	Default	Description
`name`	string	required	Unique identifier for the server
`url`	string	required	HTTPS endpoint of your MCP server
`headers`	object	`{}`	Authentication and custom headers
`timeout`	integer	`30000`	Request timeout in milliseconds
`retry`	object	`{"attempts": 2, "backoff": 1000}`	Retry configuration
`tools_filter`	array	all tools	Subset of tools to expose to the agent

Filtering Tools from a Server

If your MCP server exposes many tools but you only want the agent to use a few:

python

{
    "name": "internal-platform",
    "url": "https://mcp.yourcompany.com/platform",
    "headers": {"Authorization": "Bearer token"},
    "tools_filter": ["get_user", "search_tickets", "create_ticket"]
}

Health Checks and Monitoring

SandBase pings custom servers periodically. If a server is unreachable, tool calls will fail gracefully and the agent will inform the user.

Check server connectivity:

bash

curl https://api.sandbase.ai/api/mcp/custom/internal-crm/health \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

json

{
  "status": "healthy",
  "latency_ms": 45,
  "tools_count": 8,
  "last_checked": "2025-01-15T10:30:00Z"
}

Building Your Own MCP Server

A minimal MCP server in Python using the official SDK:

python

from mcp.server import Server
from mcp.types import Tool, TextContent

server = Server("my-custom-tools")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="lookup_customer",
            description="Look up a customer by email or ID",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Email or customer ID"}
                },
                "required": ["query"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "lookup_customer":
        customer = await db.find_customer(arguments["query"])
        return [TextContent(type="text", text=json.dumps(customer))]

# Run with SSE transport for SandBase compatibility
if __name__ == "__main__":
    from mcp.server.sse import SseServerTransport
    from starlette.applications import Starlette
    from starlette.routing import Route

    sse = SseServerTransport("/messages")
    app = Starlette(routes=[
        Route("/sse", endpoint=sse.handle_sse),
        Route("/messages", endpoint=sse.handle_post_message, methods=["POST"]),
    ])
    # Deploy with: uvicorn server:app --host 0.0.0.0 --port 8080

Tool Selection Best Practices

Choosing the right tools for your agent impacts performance, cost, and reliability.

Match Tools to Agent Purpose

Define your agent's role first, then select only the tools it needs:

Agent Type	Recommended Tools	Why
Research assistant	`web-search`, `web-fetch`, `wikipedia`	Needs information retrieval
Data analyst	`postgres`, `code-exec`, `filesystem`	Needs data access and computation
Customer support	`notion`, `email`, `slack`	Needs knowledge base and communication
DevOps bot	`github`, `shell`, `docker`, `sentry`	Needs code and infrastructure access
Content creator	`web-search`, `image-gen`, `filesystem`	Needs research and asset creation

The 3-5 Tool Rule

Agents perform best with 3-5 focused tools. Each additional tool:

Adds ~200-500 tokens to the context (tool descriptions)
Increases decision complexity for the LLM
Raises the chance of incorrect tool selection

python

# ✅ Good — focused tool set for a research agent
tools = [
    {"type": "mcp", "server": "web-search"},
    {"type": "mcp", "server": "web-fetch"},
    {"type": "mcp", "server": "wikipedia"},
]

# ❌ Bad — too many tools, agent gets confused
tools = [
    {"type": "mcp", "server": "web-search"},
    {"type": "mcp", "server": "postgres"},
    {"type": "mcp", "server": "github"},
    {"type": "mcp", "server": "email"},
    {"type": "mcp", "server": "slack"},
    {"type": "mcp", "server": "s3"},
    {"type": "mcp", "server": "docker"},
    # ... agent doesn't know which to use
]

Guide Tool Usage in System Prompts

Tell the agent when and how to use each tool:

python

system = """You are a research assistant.

TOOL USAGE GUIDELINES:
- Use web-search for current events, recent data, and factual questions
- Use wikipedia for historical context and encyclopedic information
- Use web-fetch to read full articles when search snippets aren't enough
- Always cite your sources with URLs
- If a search returns no results, tell the user honestly
- Never make up information — if you can't verify something, say so
"""

Handle Tool Errors Gracefully

Tools can fail (network issues, rate limits, server downtime). Configure your agent to handle failures:

python

system = """...
ERROR HANDLING:
- If a tool call fails, explain the issue to the user and suggest alternatives
- If web-search is unavailable, try wikipedia as a fallback
- Never retry a failed tool more than once in the same turn
- If all tools fail, provide your best answer from training data with a disclaimer
"""

Use Tool Filters for Security

When connecting to servers with broad access, restrict which tools the agent can use:

python

# Only expose read operations, not write
{
    "name": "production-db",
    "url": "https://mcp.internal.com/postgres",
    "headers": {"Authorization": "Bearer read-only-token"},
    "tools_filter": ["query", "list_tables", "describe"]
    # Excludes: execute, drop_table, alter, etc.
}

Cost Optimization

Strategy	Impact	How
Fewer tools	Lower token cost	Remove tools the agent rarely uses
Specific system prompts	Fewer unnecessary calls	Tell agent exactly when to use each tool
Tool filters	Reduced schema size	Only expose needed operations
Caching	Lower latency + cost	Platform caches repeated tool calls

Browse All Tools

Explore the full catalog of 2000+ tools at sandbase.ai/plugins.

Next Steps

Agent API — Create agents with tools
Sandboxes — Code execution environments
API Reference — Full endpoint documentation

MCP Tools ​

How It Works ​

Attaching Tools to Agents ​

Using Platform Tools ​

Using Custom MCP Servers ​

Available Tool Categories ​

Web & Search ​

Browser Automation ​

Data & Databases ​

Code Execution ​

Version Control & DevOps ​

Communication ​

File & Storage ​

AI & Generation ​

Analytics & Monitoring ​

CRM & Business ​

Listing Available Tools ​

List All MCP Servers ​

List Tools for a Server ​

Tool Execution Flow ​

Custom Server Setup Guide ​

Self-Hosted Server Requirements ​

Connecting a Custom Server ​

Authentication Options ​

Server Configuration Options ​

Filtering Tools from a Server ​

Health Checks and Monitoring ​

Building Your Own MCP Server ​

Tool Selection Best Practices ​

Match Tools to Agent Purpose ​

The 3-5 Tool Rule ​

Guide Tool Usage in System Prompts ​

Handle Tool Errors Gracefully ​

Use Tool Filters for Security ​

Cost Optimization ​

Browse All Tools ​

Next Steps ​

MCP Tools

How It Works

Attaching Tools to Agents

Using Platform Tools

Using Custom MCP Servers

Available Tool Categories

Web & Search

Browser Automation

Data & Databases

Code Execution

Version Control & DevOps

Communication

File & Storage

AI & Generation

Analytics & Monitoring

CRM & Business

Listing Available Tools

List All MCP Servers

List Tools for a Server

Tool Execution Flow

Custom Server Setup Guide

Self-Hosted Server Requirements

Connecting a Custom Server

Authentication Options

Server Configuration Options

Filtering Tools from a Server

Health Checks and Monitoring

Building Your Own MCP Server

Tool Selection Best Practices

Match Tools to Agent Purpose

The 3-5 Tool Rule

Guide Tool Usage in System Prompts

Handle Tool Errors Gracefully

Use Tool Filters for Security

Cost Optimization

Browse All Tools

Next Steps