> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Tools and connections

Operations on this page (Python SDK `sikaru_api`, authenticated `client` and `project` from the quickstart):

1. Create a remote MCP connection: `client.connections.create_connection(project, kind="mcp", display_name=..., ownership="workspace", config=ConnectionConfig(endpoint=..., auth="bearer"), credentials=ConnectionCredentials(token=...))`. Supported `auth`: `bearer`, `none`, `api_key` (needs the upstream header name), `oauth` (connection authorization flow). Public HTTPS endpoints only.
2. Discover tools: `client.connections.discover(project, connection.id)`. Discovery does not grant tools.
3. Grant tools: `client.connections.grant(project, connection.id, agent_id=..., tools=[...], environment="production", approval="always")`. `agent_id` is the managed agent's ID, not the slug. Environments: `draft`, `staging`, `production`. `approval`: `always` or `never`.
4. Dashboard path (no code): project > **Connections** > **Add Connection** > pick an app (catalog powered by Composio) > sign in; or **More Ways to Connect** > **Connect an MCP Server** (HTTPS MCP endpoint; authentication: No authentication, Bearer token, API key header, or OAuth). Then mention `@app/<mention-name>` or `@mcp/<mention-name>` in the agent document, choose tools and policy (`allow`, `require_approval`, `deny`) in the access panel, and Go live. Creating a connection alone grants nothing.
5. Internal MCP servers (stdio, localhost, private network) cannot be connected directly. Route them through Executor ([https://executor.sh](https://executor.sh)): add them to Executor, expose its single `/mcp` endpoint on public HTTPS (hosted `https://mcp.executor.sh/mcp`, or a self-hosted origin), and connect that endpoint once with `auth="oauth"`.
6. Application account via API: create a `composio` connection with `ConnectionConfig(toolkit=...)`, then `client.connections.authorize(project, connection_id)` and present the returned authorization URL to the account owner before discovery and grants.
7. Product-owned tools: register the tool-provider contract, pass tool references and capability grants when starting work, receive pending tool requests, perform the action, submit the result.
8. Maintenance: inspect status, reauthorize, revoke an agent grant, disable, or disconnect a connection.

Required permission: `tool_providers:write`. Personal connection without a signed-in user returns `needs_signed_in_user` for that call.

Tools let an agent act on information outside its conversation. Choose who should execute each action, connect the resource, and grant only the capabilities that the agent needs. Instructions alone do not grant tool access.

## Choose an execution path

```mermaid
flowchart TD
    Q{"Who should execute the action?"}
    Q -->|"Sikaru, through an authorized app or remote MCP server"| Managed["Managed connection"]
    Q -->|"Your backend, with your business logic"| Product["Product-owned tool"]
    Q -->|"A machine or workspace you control"| Local["Local compute"]
```

| Path               | Who executes the action                                                | Use it for                                                       |
| ------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Managed connection | Sikaru calls an app connected through Composio, or a remote MCP server | SaaS accounts such as HubSpot, and your own MCP tools            |
| Product-owned tool | Your backend executes the requested capability and returns a receipt   | Your product's business logic, internal APIs, and user approvals |
| Local compute      | A native executor on your machine runs admitted operations             | Work that needs a workspace or execution environment you control |

Connections require `tool_providers:write` and the corresponding service capability to be available. See [Local compute](/run/local-compute) for machine attachment and [Runs and tool requests](/run/runs-and-tool-requests) for product-owned execution.

## Connect an app from the dashboard

Sikaru's app catalog is powered by [Composio](https://composio.dev), so agents can use SaaS accounts without you writing an integration. Connect once in the dashboard, then give each agent only the tools it needs.

#### Add the connection

Open your project and go to **Connections**. Select **Add Connection** and pick the app.

#### Choose a name and owner

Set the connection name (it becomes the mention name) and its ownership: **Shared** with the project, or **Personal** so each runner connects their own account. See [Personal connections](#personal-connections).

#### Sign in

Sign in to the app to authorize it. Sikaru loads the app's tools automatically when sign-in completes.

#### Give an agent access

In the agent document, mention the app, such as `@app/hubspot`. In the access panel, choose the tools and a policy: `allow`, `require_approval`, or `deny`. Then review and **Go live**. See [Author and publish](/build/agents-and-releases).

> **Note**
>
> Creating a connection does not grant any agent access. Access changes take effect only after Go live, and Go live shows added, removed, and changed tools for review.

Remote MCP servers use the same page: open **More Ways to Connect** next to **Add Connection** and choose **Connect an MCP Server**. Enter the HTTPS MCP endpoint and choose **No authentication**, **Bearer token**, **API key header**, or **OAuth**.

## Connect a remote MCP server with the API

Sikaru connects to public HTTPS MCP servers that use the Streamable HTTP transport. stdio servers, private-network addresses, redirects, and credentials in URL query strings are not supported. To use internal servers, [route them through Executor](#connect-internal-mcp-servers-through-executor). You operate or select the upstream server; Sikaru manages its client connection.

> **Note**
>
> This does not create an MCP server endpoint for your Sikaru agent.

The following example assumes a reachable MCP endpoint that accepts bearer authentication. Read its endpoint and credential from your backend environment. Use the authenticated `client` and `project` from the quickstart.

```python
import os
from sikaru_api import ConnectionConfig, ConnectionCredentials

connection = client.connections.create_connection(
    project,
    kind="mcp",
    display_name="Knowledge tools",
    ownership="workspace",
    config=ConnectionConfig(
        endpoint=os.environ["KNOWLEDGE_MCP_URL"],
        auth="bearer",
    ),
    credentials=ConnectionCredentials(token=os.environ["KNOWLEDGE_MCP_TOKEN"]),
)
print("Connection ID:", connection.id)
discovered = client.connections.discover(project, connection.id)
```

| `auth` setting | What it needs                                                                           |
| -------------- | --------------------------------------------------------------------------------------- |
| `bearer`       | A token in `ConnectionCredentials`                                                      |
| `none`         | No credential                                                                           |
| `api_key`      | The upstream header name                                                                |
| `oauth`        | The connection authorization flow. Do not supply a token copied from a browser session. |

> **Warning**
>
> Keep credentials in authentication fields, never in endpoint query strings, prompts, or artifacts.

Discovery does not grant every tool to an agent. Inspect discovered tool names and schemas before selecting them.

## Connect internal MCP servers through Executor

Sikaru cannot reach MCP servers that run over stdio, on localhost, or inside your private network. We recommend [Executor](https://executor.sh) as a single router for all of them. Executor puts your MCP servers, OpenAPI services, and GraphQL APIs behind one MCP endpoint, so Sikaru needs only one connection.

```mermaid
flowchart LR
    Agent["Sikaru agent"] -->|"one MCP connection"| Exec["Executor /mcp"]
    Exec --> A["Internal MCP server"]
    Exec --> B["Internal OpenAPI service"]
    Exec --> C["Other MCP servers"]
```

#### Add your tools to Executor

Add each MCP server, OpenAPI spec, or GraphQL API to Executor as an app. See the [Executor docs](https://executor.sh/docs).

#### Run Executor where it can reach them

Use [Executor Cloud](https://executor.sh) for tools on public addresses. For services on private addresses, [self-host Executor](https://executor.sh/docs/run/self-host) inside your network and set `EXECUTOR_APPS_ALLOW_PRIVATE_FETCH=true`. Put a TLS terminator in front so its origin is public HTTPS.

#### Connect Executor to Sikaru

In **Connections**, choose **Connect an MCP Server**. Enter `https://mcp.executor.sh/mcp` for Executor Cloud, or `https://<your-executor-origin>/mcp` when self-hosted. Choose **OAuth** and sign in to approve the connection.

#### Grant tools per agent

Mention the connection (for example `@mcp/internal-tools`) and select only the tools each agent needs. Sikaru still enforces per-tool grants and approval policies for tools that arrive through Executor.

> **Warning**
>
> Every agent granted the Executor connection can reach only the tools you select in Sikaru, but Executor itself can reach everything you add to it. Treat its private-network access as a deliberate decision, and keep Sikaru grants narrow.

## Grant selected tools

Grant a specific discovered tool to an agent in the intended environment:

```python
client.connections.grant(
    project, connection.id,
    agent_id=os.environ["SIKARU_AGENT_ID"],
    tools=[os.environ["SIKARU_CONNECTION_TOOL_NAME"]],
    environment="production",
    approval="always",
)
```

Use the managed agent's ID for `agent_id` and an exact discovered tool name. The connection grant is distinct from the agent slug used to start runs. `draft`, `staging`, and `production` grants should match where you intend to use the connection.

With `approval="always"`, your application must handle the approval request before the action proceeds. Select `never` only where your application's policy permits unattended execution. A tool-schema change can require grant review; a new discovery result should not silently widen access.

## Connect an app with the API

Apps from the Composio catalog can also be connected programmatically:

#### Create the connection

Create a `composio` connection with the supported toolkit identifier in `ConnectionConfig(toolkit=...)`.

#### Start authorization

Call `client.connections.authorize(project, connection_id)` and present the returned authorization URL to the account owner.

#### Discover and grant

Complete the documented authorization flow before discovery and grants.

Application credentials are established through that authorization flow. Do not put application OAuth tokens into the connection configuration. A workspace connection and a personal connection express different ownership; choose the account and scope intended for the users of your product.

## Handle product-owned actions

For your own APIs, register the tool-provider contract and pass the supported tool references and capability grants when starting work. Your backend receives pending tool requests, checks application permissions, performs the action, and submits its result. Sikaru does not infer how to call an arbitrary function merely from its name.

Keep the pending action's tool-call, provider, and capability identities. Record an external action's outcome before acknowledging it, so a lost network response does not cause a duplicate email, payment, or update. The [run guide](/run/runs-and-tool-requests) shows approval and receipt submission.

## Reconnect or remove access

Inspect the connection's status when calls fail.

| Goal                                                     | Action                    |
| -------------------------------------------------------- | ------------------------- |
| Restore an account that requires reconnection            | Reauthorize it            |
| Remove one agent's access without affecting other agents | Revoke that agent's grant |
| Block future use in Sikaru                               | Disable the connection    |
| The account should no longer be connected                | Disconnect it             |

> **Warning**
>
> These operations do not undo an action already dispatched to an external service. Reconcile uncertain actions with that service before retrying.

## Personal connections

Choose **Personal** when adding an app or secret that each runner should connect individually. The project shares the named slot and its tool definitions; each signed-in user supplies their own account or value. Remote MCP servers use Shared ownership. An author may publish a personal app reference without connecting their own account.

When a signed-in run needs a missing account, its turn waits and offers Connect in the conversation. Complete authorization or enter your secret, and the same turn resumes. An API-key run receives `needs_signed_in_user` for that call and can continue with other work. Tenant and user labels do not grant personal access.

A session becomes permanently personal on its first personal tool use, including earlier messages. Only its runner can read or continue the conversation. Other project members can see that it exists, its status and aggregate usage. Disconnecting your account affects your access; revoking the connection slot removes access for every agent using it.

## Next steps

#### [Runs and tool requests](/run/runs-and-tool-requests)

Handle approvals and submit product-owned tool results.

#### [Local compute](/run/local-compute)

Attach a machine you control for workspace operations.