Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypha-docs.plinqx.app/llms.txt

Use this file to discover all available pages before exploring further.

The tools/call endpoint executes a tool with provided arguments and returns the result.

​
Endpoint

POST /mcp/tools/:name

​
Authentication

​
Authorization
string
required
Bearer token with your Plinqx API key. Format: Bearer plinqx_xxxxxxxxxxxxxxxxxxxx
Or use query parameter:
​
api_key
string
required
Your Plinqx API key

​
Path Parameters

​
name
string
required
The name of the tool to execute (as returned by tools/list)

​
Request Body

​
arguments
object
required
Tool input parameters matching the tool’s inputSchema

​
Request Example

curl -X POST 'https://hypha-api.plinqx.app/mcp/tools/sf_query' \
  -H 'Authorization: Bearer plinqx_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "arguments": {
      "query": "SELECT Id, Name FROM Account LIMIT 10"
    }
  }'

​
Response

​
Success Response

​
content
array
required
Array of content items (typically one item with the result)
​
isError
boolean
Whether the tool returned an error (false for success)

​
Content Item

​
type
string
required
Content type: “text” for text results, “image” for images, etc.
​
text
string
Text content of the result

​
Response Example

{
  "content": [
    {
      "type": "text",
      "text": "{\"records\": [{\"Id\": \"001...\", \"Name\": \"Acme Corp\"}]}"
    }
  ],
  "isError": false
}

​
Response Headers

​
X-Cache-Status
string
Cache status: “HIT”, “MISS”, or “BYPASS”
​
X-Cache-TTL
string
Time-to-live for cached response (seconds)
​
X-Idempotency-Cached
string
“true” if response was served from idempotency cache

​
Error Responses

​
400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid tool arguments",
    "details": [
      {
        "path": "query",
        "message": "Query parameter is required"
      }
    ]
  }
}

​
401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

​
403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Tool not available in your Collections"
  }
}

​
404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found"
  }
}

​
429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  }
}

​
Idempotency

Include an idempotency key to ensure requests are only processed once:
​
Idempotency-Key
string
Unique key for idempotent requests. Duplicate requests with the same key return cached response.
Idempotency keys are valid for 24 hours. Requests with the same key within 24 hours return the cached response.

​
Caching

Tool responses can be cached:
  • Cache Headers: Check X-Cache-Status header
  • Cache Bypass: Include X-Cache-Bypass: true header or ?_cache=false query param
  • TTL: Cache TTL shown in X-Cache-TTL header

​
Next Steps

List Tools

Discover available tools

REST API

Explore REST API endpoints