Tools and connections

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

Connections require tool_providers:write and the corresponding service capability to be available. See Local compute for machine attachment and Runs and tool requests for product-owned execution.

Connect an app from the dashboard

Sikaru’s app catalog is powered by Composio, 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.

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. You operate or select the upstream server; Sikaru manages its client connection.

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.

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)

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 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.

Grant selected tools

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

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:

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 shows approval and receipt submission.

Reconnect or remove access

Inspect the connection’s status when calls fail.

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