Tool Use

Tool Use Overview

Agents interact with external systems through tools. A tool is a well-defined interface that exposes operations like reading files, executing commands, querying databases, or calling APIs. Tools give agents the ability to take real actions in your infrastructure.

Riven uses the Model Context Protocol (MCP) as the standard transport layer for tool communication. MCP provides a unified interface for tool discovery, invocation, and result handling across all agent types.

MCP Integration

MCP (Model Context Protocol) is an open protocol for connecting AI agents to external tools and data sources. Riven's agent runtime implements a full MCP client, and you can connect any MCP-compatible server as a tool provider.

Each MCP server exposes a set of tools that agents can discover and invoke at runtime. The agent runtime handles serialization, error handling, and retry logic automatically.

tools:
  mcp_servers:
    - name: filesystem
      uri: mcp://localhost:3100
      transport: stdio
    - name: git
      uri: mcp://localhost:3101
      transport: stdio
    - name: kubernetes
      uri: mcp://localhost:3102
      transport: sse
      auth:
        type: bearer
        token_env: K8S_MCP_TOKEN

Supported Transports

Built-in Tools

Riven ships with several built-in MCP servers that cover the most common infrastructure operations:

• File System — Read, write, and search files within sandboxed directories. Supports glob patterns and content search.
• Git — Clone repositories, read diffs, create branches, commit changes, and manage pull requests.
• Kubernetes — List pods, read logs, apply manifests, scale deployments, and check resource status.
• Database — Execute read-only queries against PostgreSQL and MongoDB with parameterized query support.

Creating Custom Tools

You can create custom MCP servers to expose any API or system as a tool for your agents. A custom MCP server implements the MCP protocol and registers tools with typed input and output schemas.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
 
const server = new McpServer({
  name: "slack-notifier",
  version: "1.0.0",
});
 
server.tool(
  "send_message",
  "Send a message to a Slack channel",
  {
    channel: z.string().describe("Slack channel ID"),
    text: z.string().describe("Message text"),
    thread_ts: z.string().optional().describe("Thread timestamp for replies"),
  },
  async ({ channel, text, thread_ts }) => {
    const response = await fetch("https://slack.com/api/chat.postMessage", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SLACK_BOT_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ channel, text, thread_ts }),
    });
 
    const result = await response.json();
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }
);
 
server.listen({ transport: "stdio" });

Tool Authentication

Tools often need credentials to access external systems. Riven provides a secure credential injection system that passes secrets to MCP servers without exposing them in agent configuration.

Credentials are managed through Kubernetes secrets and injected as environment variables into MCP server containers. The agent itself never sees the raw credentials.

tools:
  mcp_servers:
    - name: slack-notifier
      uri: mcp://localhost:3200
      transport: stdio
      auth:
        type: env
        secrets:
          - name: SLACK_BOT_TOKEN
            from: k8s-secret/slack-credentials/bot-token
          - name: SLACK_SIGNING_SECRET
            from: k8s-secret/slack-credentials/signing-secret

MCP Troubleshooting

Connection Issues

If an agent cannot connect to an MCP server, check the following:

# Verify the MCP server pod is running
kubectl get pods -n dev-center -l app=<agent-name>
 
# Check MCP server logs
kubectl logs -n dev-center <agent-pod> -c <mcp-server-name>
 
# Test connectivity from the agent container
kubectl exec -n dev-center <agent-pod> -c agent -- \
  curl -s http://localhost:<port>/health

Common Errors

Debugging MCP Calls

Enable verbose MCP logging to see all tool invocations and responses:

tools:
  debug: true
  mcp_servers:
    - name: filesystem
      uri: mcp://localhost:3100
      transport: stdio
      timeout: 60000  # 60 seconds

With debug: true, the agent logs every MCP request and response to stdout. View these logs with:

riven agents logs <agent-name> --follow --filter mcp

Next Steps

• Skills — Composable capabilities for agents.
• Memory — Persistent memory systems for context-aware agents.
• Agents Overview — Architecture and lifecycle of Riven Agents.