Skip to content

AI Assistants (MCP)

The Portal API is also served as a Model Context Protocol (MCP) server. An AI assistant connected to it can list, create and update your campaigns, line items, creatives, targetings, trackings and read your reporting, using the same operations as the REST API.


Setting Value
URL https://portal.staging.arago-tech.com/mcp
Transport Streamable HTTP (stateless, JSON responses)
Header Authorization: Bearer <YOUR_PARTNER_API_KEY>

Tool calls go through the same authentication, validation and tenant isolation as REST calls: an assistant can only do what your API key can do. See Security & Access.

Tools that modify data (create, upsert, update, delete) carry MCP hints flagging them as write or destructive operations. Clients that honour these hints can ask for your confirmation before running them, but auto-approve modes skip it, so use a key bound to a test account while evaluating.


Area Tools
Campaign list_campaigns, get_campaign, create_campaign, update_campaign
Line item list_line_items, get_line_item, upsert_line_items, delete_line_items
Creative list_creatives, get_creatives, get_creative, upsert_creatives, upload_asset
Audit get_audits, upsert_audits
Targeting get_targetings, get_targeting_by_id, upsert_targetings, delete_targetings
Tracking get_trackings, upsert_trackings, delete_trackings
Pricing get_pricing_policies, upsert_pricing_policies
DCO get_dynamic_content_optimizations, get_dynamic_content_optimization, upsert_dynamic_content_optimizations, delete_dynamic_content_optimizations
Geo get_area_geometries, get_areas, upsert_area
Reporting get_impressions_ranges, get_campaign_reporting, get_campaign_reporting_series, generate_campaign_report, get_line_items_reporting, get_line_items_reporting_series

Each tool carries a description, the input schema and the field descriptions of the matching operation in the Portal API Reference. The required lists of the input schema name the fields the operation needs. Request validation is the same as REST: for example pagination.limit must be at least 10, and a lower value returns a tool result with isError: true and InvalidArgument rather than a result.


Avoid writing the API key in plain text in a client configuration file. Keep it in your OS keyring and read it when the client starts:

Terminal window
# store once (prompts for the key)
secret-tool store --label="Arago Portal API key" service arago-portal
# read it
secret-tool lookup service arago-portal

The examples below use the Linux command. On macOS, replace it with the Keychain one.


Add a .mcp.json file to your project. Claude Code expands ${PORTAL_API_KEY} from the environment, so the key never lands in the file:

.mcp.json
{
"mcpServers": {
"portal": {
"type": "http",
"url": "https://portal.staging.arago-tech.com/mcp",
"headers": { "Authorization": "Bearer ${PORTAL_API_KEY}" }
}
}
}

Start Claude Code with the key read from the keyring, then run /mcp to check the portal tools are listed:

Terminal window
PORTAL_API_KEY="$(secret-tool lookup service arago-portal)" claude

List the tools without any AI client:

List tools
curl -s https://portal.staging.arago-tech.com/mcp \
-H "Authorization: Bearer $(secret-tool lookup service arago-portal)" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

A missing or unknown Authorization key is rejected with 401 Unauthorized before the request reaches MCP, so tools/list itself verifies the key. Tool errors on a valid key, for example an argument the server rejects, return a tool result with isError: true and carry the gRPC status name (InvalidArgument, NotFound, Internal) rather than the REST codes listed in Error Handling.

A request that breaks a validation or business rule, such as a budget under the 10 USD minimum, is an InvalidArgument, the REST API answers it with a 400. The details of the error name the field, the rule code (for example GTE) and its parameters.


A request the server cannot process as JSON-RPC returns a JSON-RPC error object with the matching code:

Code Cause HTTP status
-32700 The body is not valid JSON 400
-32600 The body is not a valid JSON-RPC request, for example it has no id 400
-32601 The method does not exist 400
-32602 The tool does not exist, or an argument of the tool call has the wrong type 200
{
"jsonrpc": "2.0",
"id": 7,
"error": { "code": -32601, "message": "Method not found: \"foo/bar\"" }
}

The id is the one of the request, or null when the request has none or cannot be parsed.