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.
Endpoint & Authentication
Section titled “Endpoint & Authentication”| 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.
Available Tools
Section titled “Available Tools”| 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.
Storing the API Key
Section titled “Storing the API Key”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:
# store once (prompts for the key)secret-tool store --label="Arago Portal API key" service arago-portal
# read itsecret-tool lookup service arago-portal# store once (prompts for the key)security add-generic-password -s arago-portal -a "$USER" -w
# read itsecurity find-generic-password -s arago-portal -wThe examples below use the Linux command. On macOS, replace it with the Keychain one.
Client Setup
Section titled “Client Setup”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:
{"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:
PORTAL_API_KEY="$(secret-tool lookup service arago-portal)" claudeClaude Desktop’s remote connectors expect OAuth, so bridge the HTTP endpoint with
mcp-remote to pass the API key as a header.
The shell wrapper reads the key from the keyring at launch:
{"mcpServers": { "portal": { "command": "sh", "args": [ "-c", "exec npx -y mcp-remote https://portal.staging.arago-tech.com/mcp --header \"Authorization: Bearer $(secret-tool lookup service arago-portal)\"" ] }}}Restart Claude Desktop after editing the file.
VS Code prompts for the key once and keeps it in its own secret storage, so no keyring command is needed:
{"inputs": [ { "id": "portal-api-key", "type": "promptString", "description": "Arago Portal API key", "password": true }],"servers": { "portal": { "type": "http", "url": "https://portal.staging.arago-tech.com/mcp", "headers": { "Authorization": "Bearer ${input:portal-api-key}" } }}}Open Copilot Chat in Agent mode and enable the portal tools from the tools picker.
Checking the Connection
Section titled “Checking the Connection”List the tools without any AI client:
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.
Protocol Errors
Section titled “Protocol Errors”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.