The Everflow MCP Server exposes read-only tools across four reference pages.
All tools are read-only. The MCP Server cannot create, update, or delete data.
Quick reference
| Tool | Page | Use when |
|---|
| get_report_schema | Reporting | Discover valid dimensions, filters, and metrics for run_performance_report |
| run_performance_report | Reporting | Aggregated stats grouped by dimension — offers, affiliates, dates, geo, device, etc. |
| run_network_summary | Reporting | Overall totals for a date range, with optional prior-period comparison |
| search_activity | Reporting | Raw click or conversion records within a time window — set type to choose the event stream |
| get_offer | Offers & Affiliates | Full offer detail — caps, targeting, payout, affiliate access |
| list_offers | Offers & Affiliates | Paginated offer list with filters |
| get_affiliate | Offers & Affiliates | Full affiliate detail — activity, users, offer access |
| list_affiliates | Offers & Affiliates | Paginated affiliate list with filters |
| get_account_info | Account & Generic | Network settings and authenticated user details |
| get_entity_schema | Account & Generic | Discover filters and includes for any entity type |
| get_entity | Account & Generic | Single entity by ID for any supported type — for click, conversion, and transaction (full attribution chain) see Events & Attribution |
| list_entities | Account & Generic | Paginated entity list for any supported type |
| search_documentation | Account & Generic | Search Everflow’s help center and API docs |
| Deprecated tool | Use instead |
|---|
get_click(transaction_id=X) | get_entity(type="click", id=X) |
get_conversion(conversion_id=X) | get_entity(type="conversion", id=X) |
search_clicks(from, to, …) | search_activity(type="click", from, to, …) |
search_conversions(from, to, …) | search_activity(type="conversion", from, to, …) |
Error responses
When a tool call fails, the MCP Server returns a result with isError: true. The text field of that result is a JSON object with two fields:
{
"code": "INVALID_ARGUMENT",
"message": "Missing required parameter: 'transaction_id'."
}
message is human-readable and safe to surface directly to an end user or AI agent. The code is a stable string your code can branch on without parsing prose.
Error codes
| Code | Meaning | Common triggers |
|---|
INVALID_ARGUMENT | A parameter is missing, malformed, or out of range | Missing required field (transaction_id, from/to, dimensions); invalid date format; filters JSON exceeds 4,096 characters; a string parameter exceeds its length limit (see Limits & Constraints) |
UNAUTHENTICATED | The API key was not recognized by Everflow | Key is missing, expired, or belongs to an affiliate/advertiser rather than a network user |
PERMISSION_DENIED | The key is valid but lacks the required module permission for this tool | A scoped employee key without Offer Management access calling get_offer; a key without Reporting access calling run_performance_report |
INTERNAL | An unexpected error occurred in the Everflow backend | Transient service failure; try again. If it persists, email support@everflow.io |
Handling errors in a script
Check isError before processing content. The code field lets you handle each class of error differently without string-matching the message:
import json
def call_tool(agent_response):
for block in agent_response.content:
if not hasattr(block, "text"):
continue
# Attempt to detect an error envelope: {"code": "...", "message": "..."}
try:
payload = json.loads(block.text)
except json.JSONDecodeError:
# Not JSON — treat as a successful plain-text result
return block.text
# Valid JSON but not an error envelope — successful structured result
if "code" not in payload:
return block.text
code = payload.get("code")
message = payload.get("message", "Unknown error")
if code == "INVALID_ARGUMENT":
raise ValueError(f"Bad request: {message}")
elif code == "UNAUTHENTICATED":
raise PermissionError(f"Auth failed: {message}")
elif code == "PERMISSION_DENIED":
raise PermissionError(f"Insufficient permissions: {message}")
elif code == "INTERNAL":
raise RuntimeError(f"Server error: {message}")
AI agents (Claude, Gemini, etc.) read the message field automatically and will describe the problem in natural language without any extra handling on your part. Error code parsing is only necessary when you are processing MCP tool results programmatically in a script.
