toolsconnector 0.3.12

A foundational primitive for standardizing external API tool connections — for both traditional applications and AI agents.

ToolsConnector

One interface, every tool. Connect 68+ APIs to your Python app or AI agent in minutes.

---

The Problem

Every SaaS API has its own SDK, its own auth dance, its own pagination scheme, and its own error format. If you're building an AI agent, you also need to generate JSON Schema for function calling -- differently for OpenAI, Anthropic, and Gemini. You end up writing glue code instead of product code.

ToolsConnector gives you a single, typed Python interface to 68 connectors and 1,370 actions. It works identically whether you're building a Django app, an OpenAI agent, or an MCP server for Claude Desktop.

Run the Documentation Site

To browse the full connector reference, playground, and guides locally:

python3 -m http.server 5001 --directory site

Then open http://localhost:5001 in your browser.

---

Install

pip install toolsconnector

Install only the connectors you need:

pip install "toolsconnector[gmail,slack,github]"

Or install a full category:

pip install "toolsconnector[communication,databases,mcp]"

Quick Start

from toolsconnector.serve import ToolKit

kit = ToolKit(
    ["gmail", "slack"],
    credentials={"gmail": "ya29.access-token", "slack": "xoxb-bot-token"},
)

# List unread emails
result = kit.execute("gmail_list_emails", {"query": "is:unread", "max_results": 5})

# Send a Slack message
kit.execute("slack_send_message", {"channel": "#general", "text": "Deployed v2.1"})

That's it. Same ToolKit, same .execute(), every connector.

Try the Examples

Want to see real integrations end-to-end? examples/ has 10 copy-pasteable scripts covering every major usage pattern. Pick one closest to what you want to build:

Pattern	Script
5-minute intro: ToolKit + execute	01_basic_usage.py
One-line MCP server for Claude Desktop / Cursor	02_mcp_server.py
OpenAI function-calling agent (full tool-use loop)	03_openai_function_calling.py
Anthropic Claude tool-use agent	04_anthropic_tool_use.py
Multi-connector agent with safety filtering	05_multi_connector.py
tc CLI walkthrough	06_cli_usage.sh
Multi-tenant ToolKitFactory (per-user isolation)	07_multi_tenant.py
Expose connectors as REST API (Starlette + uvicorn)	08_rest_api.py
CI health checks, spec extraction, OpenAPI export	09_health_check.py
Publish to LinkedIn end-to-end	10_linkedin_publish.py

See examples/README.md for the full table with required env vars.

---

Key Features

• 68 connectors, 1,370 actions across 20 categories -- communication, social, databases, DevOps, CRM, AI/ML, AWS infrastructure, and more
• Dual-use design -- works for traditional Python apps (Django, Flask, FastAPI) and AI agents (function calling, tool use) with zero code changes
• One-line MCP server -- expose any combination of connectors to Claude Desktop, Cursor, or any MCP client
• Schema generation -- produces OpenAI, Anthropic, and Gemini function-calling schemas from the same source of truth
• Type-safe everywhere -- Pydantic V2 models for all inputs and outputs, with full JSON Schema generation
• Async-first, sync-friendly -- every action has both await kit.aexecute() and kit.execute() paths
• Circuit breakers -- per-connector failure isolation so one dead API doesn't take down your agent
• Timeout budgets -- per-action and per-request deadlines with automatic retry on transient failures
• Dry-run mode -- validate destructive actions without executing them
• BYOK auth -- bring your own API keys and tokens; no OAuth server required in the library
• Minimal dependencies -- core requires only pydantic, httpx, and docstring-parser

---

Workflows

1. Direct Python Usage

Use connectors directly in any Python application.

from toolsconnector.serve import ToolKit

kit = ToolKit(["github"], credentials={"github": "ghp_your_token"})

# List open issues
issues = kit.execute("github_list_issues", {
    "owner": "myorg",
    "repo": "myproject",
    "state": "open",
})

2. MCP Server (One Line)

Expose connectors to Claude Desktop, Cursor, Windsurf, or any MCP client.

from toolsconnector.serve import ToolKit

kit = ToolKit(
    ["gmail", "gcalendar", "notion"],
    credentials={"gmail": "ya29.token", "gcalendar": "ya29.token", "notion": "ntn_key"},
)
kit.serve_mcp()  # stdio transport, ready for Claude Desktop

Or from the command line:

# Stdio (one client per process — Claude Desktop launches it as subprocess)
tc serve mcp gmail gcalendar notion --transport stdio

# Long-lived HTTP daemon — multiple agents share one process
tc serve mcp gmail slack github --transport streamable-http --port 9000

The HTTP transport (streamable-http) accepts many concurrent client sessions on the same port — one daemon serves N agents. Per-tool circuit breakers and timeout budgets apply fairly across all clients. There's no built-in auth on the HTTP transport; put it behind a reverse proxy before exposing it publicly.

3. OpenAI Function Calling

Generate tool schemas and execute tool calls from OpenAI responses.

from openai import OpenAI
from toolsconnector.serve import ToolKit

client = OpenAI()
kit = ToolKit(["gmail", "slack"], credentials={...})

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize my unread emails"}],
    tools=kit.to_openai_tools(),
)

# Execute the tool call the model chose
tool_call = response.choices[0].message.tool_calls[0]
result = kit.execute(tool_call.function.name, tool_call.function.arguments)

4. Anthropic Tool Use

Works the same way with Claude's tool use API.

import anthropic
from toolsconnector.serve import ToolKit

client = anthropic.Anthropic()
kit = ToolKit(["jira", "slack"], credentials={...})

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Create a bug ticket for the login issue"}],
    tools=kit.to_anthropic_tools(),
)

# Execute the tool call
for block in response.content:
    if block.type == "tool_use":
        result = kit.execute(block.name, block.input)

5. Google Gemini

Generate Gemini-compatible function declarations.

from toolsconnector.serve import ToolKit

kit = ToolKit(["gmail"], credentials={...})
declarations = kit.to_gemini_tools()
# Pass to google.generativeai as function_declarations

6. CLI Usage

Manage connectors and execute actions from the terminal.

# List all available connectors
tc list

# List actions for a specific connector
tc gmail actions

# Execute an action
tc gmail list_emails --query "is:unread" --max_results 5

# Export the connector spec
tc gmail spec --format json

7. REST API

Serve connectors as HTTP endpoints with Starlette/ASGI.

from toolsconnector.serve import ToolKit

kit = ToolKit(["stripe", "hubspot"], credentials={...})
app = kit.create_rest_app(prefix="/api/v1")

# Run with uvicorn: uvicorn myapp:app --port 8000
# POST /api/v1/stripe/create_charge {"amount": 5000, "currency": "usd"}

---

Error Handling

Every connector raises typed exceptions from toolsconnector.errors so your code can branch on the failure mode instead of parsing HTTP status codes:

from toolsconnector.errors import (
    InvalidCredentialsError, TokenExpiredError, PermissionDeniedError,
    NotFoundError, RateLimitError, ValidationError, ServerError,
)

try:
    await kit.aexecute("gmail_send_email", {...})
except TokenExpiredError:
    await refresh_oauth_token()
    # ...retry...
except RateLimitError as e:
    await asyncio.sleep(e.retry_after_seconds)  # parsed from Retry-After header
    # ...retry...
except InvalidCredentialsError:
    prompt_user_to_reauthenticate()
except NotFoundError:
    return None  # 404 — caller decides what "missing" means
except PermissionDeniedError:
    request_additional_oauth_scopes()
except ValidationError:
    # 400 / 422 — your arguments were rejected by the upstream API
    raise
except ServerError:
    # 5xx — upstream is having a bad day; retry-eligible
    pass

All typed errors carry connector, action, upstream_status, and a truncated details["body_preview"] — useful for logs and observability. The full taxonomy lives in src/toolsconnector/errors/ if you want to match more granular cases (e.g. ConflictError for 409).

---

Supported Connectors

68 connectors, 1,370 actions across 20 categories.

Communication (7)

Connector	Install Extra	Actions
Gmail	gmail	38
Slack	slack	51
Discord	discord	25
Microsoft Outlook	outlook	23
Microsoft Teams	teams	17
Twilio	twilio	20
Telegram	telegram	26

Project Management (4)

Connector	Install Extra	Actions
Jira	jira	28
Asana	asana	38
Linear	linear	19
Trello	trello	25

CRM & Support (5)

Connector	Install Extra	Actions
HubSpot	hubspot	19
Salesforce	salesforce	21
Zendesk	zendesk	16
Freshdesk	freshdesk	23
Intercom	intercom	16

Code Platforms (2)

Connector	Install Extra	Actions
GitHub	github	37
GitLab	gitlab	21

Knowledge (2)

Connector	Install Extra	Actions
Notion	notion	24
Confluence	confluence	25

Storage (2)

Connector	Install Extra	Actions
Google Drive	gdrive	22
AWS S3	s3	20

Database (5)

Connector	Install Extra	Actions
Airtable	airtable	26
Firebase Firestore	firestore	17
MongoDB Atlas	mongodb	16
Redis (Upstash)	redis	18
Supabase	supabase	16

DevOps (5)

Connector	Install Extra	Actions
Cloudflare	cloudflare	23
Datadog	datadog	22
Docker Hub	dockerhub	14
PagerDuty	pagerduty	16
Vercel	vercel	16

Finance (2)

Connector	Install Extra	Actions
Stripe	stripe	40
Plaid	plaid	17

Marketing (2)

Connector	Install Extra	Actions
Mailchimp	mailchimp	23
SendGrid	sendgrid	20

AI / ML (3)

Connector	Install Extra	Actions
OpenAI	openai	26
Anthropic	anthropic	14
Pinecone	pinecone	15

Analytics (2)

Connector	Install Extra	Actions
Mixpanel	mixpanel	14
Segment	segment	14

Message Queue (2)

Connector	Install Extra	Actions
AWS SQS	sqs	16
RabbitMQ	rabbitmq	21

Security (2)

Connector	Install Extra	Actions
Okta	okta	21
Auth0	auth0	27

Productivity (6)

Connector	Install Extra	Actions
Google Calendar	gcalendar	20
Google Docs	gdocs	5
Google Sheets	gsheets	16
Google Tasks	gtasks	13
Calendly	calendly	20
Figma	figma	22

E-Commerce (1)

Connector	Install Extra	Actions
Shopify	shopify	27

Custom (1)

Connector	Install Extra	Actions
Webhook	webhook	12

---

Architecture

ToolsConnector is structured as four layers, each with a single responsibility:

+------------------------------------------------------------------+
|  Serve Layer       ToolKit, MCP, REST, CLI, Schema Generation    |
+------------------------------------------------------------------+
|  Runtime Engine    BaseConnector, @action, Middleware, Auth       |
+------------------------------------------------------------------+
|  Connectors        Gmail, Slack, GitHub, Stripe, ... (68)        |
+------------------------------------------------------------------+
|  Spec Types        Pydantic V2 models, JSON Schema, Contracts    |
+------------------------------------------------------------------+

Spec -- Pure Pydantic V2 models defining the language-agnostic connector contract. No implementation logic. These drive schema generation, MCP serving, documentation, and code generation.

Runtime -- The execution engine. BaseConnector is the abstract base class. The @action decorator parses type hints and docstrings to generate JSON Schema automatically. Middleware handles retry, rate limiting, auth refresh, and structured logging.

Connectors -- 68 implementations, each following the same pattern: subclass BaseConnector, set metadata, implement @action methods. Most use raw httpx for direct HTTP calls. Google and AWS connectors use official SDKs where protocol complexity justifies it.

Serve -- The ToolKit ties everything together. Configure once with a list of connectors and credentials, then serve as MCP, generate OpenAI/Anthropic/Gemini schemas, expose as REST, or call directly from Python.

Adding a Connector

Every connector follows the same structure:

from toolsconnector.runtime import BaseConnector, action
from toolsconnector.spec.connector import ConnectorCategory, ProtocolType

class MyService(BaseConnector):
    name = "myservice"
    display_name = "My Service"
    category = ConnectorCategory.COMMUNICATION
    protocol = ProtocolType.REST
    base_url = "https://api.myservice.com/v1"

    @action(description="List all items", idempotent=True)
    async def list_items(self, limit: int = 20) -> list[dict]:
        """List items from the service.

        Args:
            limit: Maximum number of items to return.
        """
        resp = await self._request("GET", "/items", params={"limit": limit})
        return resp.json()["items"]

The @action decorator handles everything: it parses the type hints and docstring to generate JSON Schema, creates a sync wrapper, and registers the method for discovery by ToolKit.

---

Contributing

1. Fork the repository
2. Create a connector under src/toolsconnector/connectors/yourservice/
3. Subclass BaseConnector and implement @action methods
4. Add types in a types.py module using Pydantic V2 models
5. Add the install extra to pyproject.toml
6. Write tests under tests/connectors/yourservice/
7. Submit a pull request

See the existing connectors (e.g., src/toolsconnector/connectors/slack/) for reference implementations.

Requirements

• Python 3.9+
• Core dependencies: pydantic>=2.0, httpx>=0.25, docstring-parser>=0.15
• Connector-specific dependencies installed via extras (e.g., gmail extra installs google-api-python-client)

License

Apache License 2.0. See LICENSE for details.