HTTP API and agent quickstart

These examples use https://tinyagenttools.com. For local development, replace that origin with http://localhost:8080 or http://localhost:5173.

Generated OpenAPI 3.1 reference · Current catalogue and limits

Run a bounded operation

curl -s https://tinyagenttools.com/api/v1/tools/tool-schema-checker/run \
  -H 'Content-Type: application/json' \
  -d '{"schema":{"type":"integer"},"instance":42}'

POST application/json to /api/v1/tools/SLUG/run. Server operations share tested handlers. Browser-local operations have no HTTP/MCP endpoint.

MCP

{"mcpServers":{"tiny-agent-tools":{"url":"https://tinyagenttools.com/mcp"}}}

Streamable HTTP at /mcp, official Go SDK v1.6.0, pinned MCP 2025-11-25. Eight tools: schema_validate, json_repair_preview, jsonl_inspect, token_count, mcp_check, oauth_discovery_check, artifact_preflight and document_to_markdown. Stateless JSON responses; no listening stream or retained session. The client sends Mcp-Protocol-Version: 2025-11-25 after initialize. Operation errors return isError; malformed/unknown protocol calls are protocol errors. Read rule versions, scopes and review flags before using outputs.

Temporary webhook lifecycle

curl -s https://tinyagenttools.com/api/v1/tools/temporary-webhook-inbox/run \
  -H 'Content-Type: application/json' \
  -d '{"action":"create","ttlSeconds":300,"config":{},"id":"","readToken":""}'

Save the returned id, writeURL and separate readToken privately in your client. Never place read/delete tokens in URLs. This page and the application logs do not retain capabilities.

curl -s "$WRITE_URL" -X POST -H 'Content-Type: text/plain' --data 'test payload'
curl -s "https://tinyagenttools.com/api/v1/fixtures/$ID" -H "Authorization: Bearer $READ_TOKEN"
curl -s -X DELETE "https://tinyagenttools.com/api/v1/fixtures/$ID" -H "Authorization: Bearer $READ_TOKEN"

Measure direct egress

Create agent-egress-test with the same empty config, then call its writeURL directly from the agent execution environment. Read events using the separate capability. An MCP wrapper or this server calling a URL would measure that caller, so egress is not exposed through MCP. Only direct peer IP or one forwarded IP from the configured trusted proxy is used; local/reserved addresses are withheld.

Simulations

mock-http-mcp-endpoint config uses mode:"mcp" for the fixed initialize/list/echo template, or mode:"http", status, body, delayMs and supported X-Mock-Label/Retry-After headers. mock-llm-streaming-api uses chunks, delayMs and optional errorAt; POST model/messages/stream:true to its writeURL. No inference, scripts, external calls or full provider parity.

Documents

curl -s https://tinyagenttools.com/api/v1/documents -F '[email protected]'
# Pass returned uploadID/uploadToken to document_to_markdown or the HTTP operation.
# The input file is single-use and removed before conversion; references expire after five minutes.

Only DOCX and text-based PDF, max 1 MiB / 20 PDF pages / 256 KiB Markdown. The restricted worker has no network, OCR or models. DOCX headings, simple tables and flattened lists are approximate; PDF reading order may be lost. Base64 is supported for small reproducible fixtures; use multipart and single-use references for agent workflows.

Limits, retention and errors

Thirty HTTP/MCP requests per minute per caller, two operation jobs globally, per-tool limits from the catalogue. Rate limits return 429 and Retry-After:60; busy operations return 503. Other statuses: 400 malformed JSON/protocol, 403 Origin rejected, 408 timeout, 413 bytes/output, 422 unsupported input, 404 unavailable capability and 410 disabled tool.

Five active fixtures per caller / 200 globally; TTL 30–900 seconds, 20 events / 16 KiB each, four simultaneous mock responses/streams. Read/write checks reject expired records immediately; physical SQLite/file cleanup runs on startup and every 30 seconds. Unused document uploads: two per caller / ten globally, five-minute expiry. Captures omit cookies, authorization and queries; selected headers are bounded. Stateless operations keep no input history. Outbound diagnostics disclose remote requests; OSV requires agreement. Server logs include operation/status/duration only.