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

# Custom Tools

> Create custom HTTP tools and connect external tool servers via MCP to extend your agent's capabilities.

# Custom Tools

Extend your agent beyond the built-in tools in two ways: call your own HTTP APIs, or connect external tool servers via MCP.

## Calling your own APIs

Custom HTTP integrations are configured through the unified **[API & Webhooks](/docs/tools/api-webhooks)** tool. It covers everything the old "Custom Tool (API)" did — and more:

* **API Endpoints mode** — define each endpoint (or import an OpenAPI spec) as a named, typed function the agent calls directly. This is the recommended path.
* **Free-form Request mode** — let the agent compose its own requests under a base URL.
* **Webhook mode** — fire-and-forget POSTs to Zapier / Make / n8n / custom URLs.

See the [API & Webhooks](/docs/tools/api-webhooks) page for setup, auth, OpenAPI import, and troubleshooting.

## MCP (Model Context Protocol) Integration

MCP lets you connect external tool servers to your agents. An MCP server exposes a set of tools over a standardized protocol, so your agent can discover and use them automatically.

### What is MCP?

MCP is an open protocol that standardizes how AI agents communicate with tool servers. Instead of configuring each tool individually, you point your agent at an MCP server and it automatically discovers all available tools.

### Connecting an MCP Server

1. Go to your agent's **Tools** section.
2. Click **Add Tool** and select **MCP Server**.
3. Enter the MCP server URL:

```bash theme={null}
# Example MCP server endpoints
MCP_SERVER_URL=https://your-mcp-server.com/mcp
MCP_SERVER_URL=http://localhost:3001/mcp
```

4. Configure authentication if required (API key or bearer token).
5. Click **Discover Tools** — thinnestAI will fetch the list of available tools from the server.
6. Select which tools to enable for your agent.
7. Save.

### Running Your Own MCP Server

You can build an MCP server to expose your internal tools and APIs:

```bash theme={null}
# Install an MCP server framework
npm install @modelcontextprotocol/server

# Or use Python
pip install mcp
```

Your MCP server defines tools with schemas, and thinnestAI agents can call them just like built-in tools.

### MCP Use Cases

* **Internal APIs** — Expose company-specific tools without building custom integrations for each one.
* **Shared tool servers** — One MCP server can serve tools to multiple agents.
* **Third-party MCP servers** — Connect to the growing ecosystem of public MCP servers.

## Best Practices

### Tool Naming

* Use `snake_case` names: `check_inventory`, `create_order`, `get_user_info`.
* Make names action-oriented: the agent should understand what the tool *does*.

### Descriptions

* Describe inputs and outputs clearly.
* Mention edge cases: "Returns null if the user is not found."
* Include example values when helpful.

### Error Handling

* Your API should return meaningful error messages.
* The agent will read error responses and can explain them to the user or retry.
* Use standard HTTP status codes (400 for bad input, 404 for not found, etc.).

### Security

* Use HTTPS for all production endpoints.
* Rotate API keys regularly.
* Limit tool permissions to only what the agent needs (read-only if possible).
* Consider rate limiting on your API to prevent excessive calls.

## Example: Order Status Checker

Here's a complete example of a custom tool that checks order status:

**Tool Configuration:**

| Field       | Value                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Name        | `check_order_status`                                                                                                                       |
| Description | Look up the status of a customer order by order ID. Returns the current status, estimated delivery date, and tracking number if available. |
| Endpoint    | `https://api.yourstore.com/orders/{order_id}/status`                                                                                       |
| Method      | GET                                                                                                                                        |
| Headers     | `Authorization: Bearer sk-store-api-key`                                                                                                   |

**Parameters:**

| Name      | Type   | Required | Description                    |
| --------- | ------ | :------: | ------------------------------ |
| order\_id | string |    Yes   | The order ID (e.g., ORD-12345) |

**Agent conversation:**

```
User:    "Where's my order ORD-78901?"
Agent:   [calls check_order_status with order_id="ORD-78901"]
Agent:   "Your order ORD-78901 is currently in transit. It's expected to
          arrive by March 8th. Your tracking number is 1Z999AA10123456784."
```

## Next Steps

* **[CRM & Webhooks](/docs/tools/crm-webhooks)** — Connect to CRMs and send data to external systems.
* **[Built-in Tools](/docs/tools/built-in-tools)** — Browse all pre-built tools available.