Skip to main content

MCP Tools

The platform integrates with the Model Context Protocol (MCP) to give conversations access to external tools, resources, and prompts. MCP servers are registered on the platform and their capabilities are exposed to the LLM during generation.

How It Works​

  1. When a message is sent, the platform includes available tool definitions in the LLM request
  2. If the LLM decides a tool is needed, it returns a tool call request
  3. The platform executes the tool via the MCP service (or asks for approval)
  4. The tool result is fed back to the LLM
  5. The LLM produces its final response incorporating the tool output

Discovering Available Tools​

List MCP Servers​

See which MCP servers are available on the platform:

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-list-available-servers \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Get Server Info​

Get details about a specific MCP server, including its capabilities:

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-get-server-info \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server"
  }'

List Tools​

List all tools available from a specific MCP server:

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-list-tools \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server"
  }'

Returns the tool name, description, and JSON Schema for the input parameters.

Calling Tools Directly​

You can call MCP tools directly outside of a conversation:

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-call-tool \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server",
    "tool_name": "search_memories",
    "arguments": {
      "query": "user preferences"
    }
  }'

Tool Approval Flow​

Some tools require explicit user approval before execution. When the LLM requests a tool call that needs approval:

  1. The generation run pauses
  2. The tool call is added to the pending approvals list
  3. The client polls for or is notified of pending approvals
  4. The client submits approvals (approve or deny)
  5. Generation resumes with the approved tool results

Check Pending Approvals​

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/list-pending-approvals \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc"
  }'

Submit Approvals​

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/submit-tool-approvals \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc",
    "approvals": [
      {
        "tool_call_id": "call_abc123",
        "approved": true
      }
    ]
  }'

Set approved to false to deny the tool call. The LLM will be informed that the tool was denied and will adjust its response accordingly.

Client-Side Tools​

Some tools are designed to execute on the client side (e.g., displaying a UI component, navigating to a page). When the LLM calls a client-side tool:

  1. The tool call is delivered to the client
  2. The client executes the action locally
  3. The client submits the result back to the platform
curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/submit-client-tool-results \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc",
    "tool_results": [
      {
        "tool_call_id": "call_xyz789",
        "result": "{\"navigated_to\": \"/settings\"}"
      }
    ]
  }'

Resources​

MCP servers can also expose resources — structured data that the LLM can reference.

List Resources​

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-list-resources \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server"
  }'

Read a Resource​

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-read-resource \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server",
    "resource_uri": "memory://user/preferences"
  }'

Prompts​

MCP servers can expose reusable prompt templates.

List Prompts​

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-list-prompts \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server"
  }'

Get a Prompt​

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/mcp-get-prompt \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "memory-server",
    "prompt_name": "summarize_history",
    "arguments": {
      "conversation_key": "conv_abc"
    }
  }'