Calling Tools
Invoke tools via the MCP protocol or the REST API and handle responses.
Calling via MCP Protocol
The standard way to call tools is through the MCP protocol. Send a JSON-RPC request with the tools/call method to your server's MCP endpoint at /mcp/{slug}.
Request:
curl -X POST https://api.agentdojo.dev/mcp/my-server \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "pushover-notifications-send-notification",
"arguments": {
"message": "Hello from Agent Dojo!",
"title": "Test"
}
}
}'Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Notification sent successfully. Message ID: msg_abc123"
}
],
"isError": false
}
}Calling via REST API
You can also call tools directly through the REST API using the /mcp/tools/call endpoint. This is useful for direct integrations that do not use the full MCP protocol.
curl -X POST https://api.agentdojo.dev/mcp/tools/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "pushover-notifications-send-notification",
"arguments": {
"message": "Hello from Agent Dojo!",
"title": "Test"
}
}'Response:
{
"content": [
{
"type": "text",
"text": "Notification sent successfully. Message ID: msg_abc123"
}
],
"isError": false
}Response Format
All tool call responses follow the MCP content format with two key fields:
| Field | Type | Description |
|---|---|---|
| content | array | Array of content objects. Each object has a type (typically "text") and a text field with the result. |
| isError | boolean | Set to false on success. When true, the content array contains the error message instead of the result. |
Error Handling
When a tool call fails, Agent Dojo returns structured error responses. The error codes follow JSON-RPC conventions:
The requested tool name does not exist on this server.
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Tool not found: unknown-tool-name"
}
}The tool exists but has no backing function configured.
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "No function configuration found for tool"
}
}The function was invoked but returned an error during execution.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Error: Invalid API key provided for Pushover"
}
],
"isError": true
}
}Rate Limits
Tool calls are subject to rate limiting to ensure fair usage and platform stability:
| Endpoint | Limit |
|---|---|
| /mcp/tools/call | 1,000 requests per minute |
| /mcp/tools/list | 100 requests per minute |
Note: When a rate limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.