Nexoya API

Appearance

What is the Nexoya MCP? ​

The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude securely connect to external tools and data sources. The Nexoya MCP server exposes your marketing portfolios, performance data, attribution results, and optimization proposals to any MCP-compatible client; so you can ask questions like "What does the latest optimization recommend for my Italian portfolio?" directly in chat.

Prerequisite Knowledge

Before continuing, it helps to be familiar with the Nexoya platform concepts: teams, portfolios, contents, funnel steps, and optimizations. If MCP is new to you, the official MCP documentation is a good place to start.

Connecting to the Nexoya MCP ​

The Nexoya MCP server uses OAuth 2.1 with Dynamic Client Registration. You sign in with your existing Nexoya credentials; no API key is required.

TransportEndpointStatus
Streamable HTTPhttps://mcp.nexoya.com/mcpRecommended
Server-Sent Events (SSE)https://mcp.nexoya.com/sseDeprecated
  • Auth: OAuth 2.1 (Dynamic Client Registration)
  • Requirements: Active paid Nexoya account. Contact sales@nexoya.com to request access.

SSE endpoint is deprecated

The SSE endpoint (https://mcp.nexoya.com/sse) remains available but is deprecated. Migrate to the Streamable HTTP endpoint (https://mcp.nexoya.com/mcp) for all new integrations.

In Claude.ai ​

  1. Open Settings → Connectors.
  2. Find Nexoya in the directory and click Connect.
  3. Sign in with your Nexoya credentials when redirected.
  4. Approve the requested scopes.

As a custom connector ​

For MCP clients that are not Claude.ai, or if you want to connect manually:

  1. Open Settings → Connectors → Add custom connector (or the equivalent in your client).
  2. Paste https://mcp.nexoya.com/mcp as the server URL.
  3. Complete the OAuth sign-in flow.
Example prompts

Once connected, try these in Claude:

  • "List the teams I have access to."
  • "Show me the portfolios in team 42."
  • "Give me the performance for portfolio 1234 from 2025-04-01 to 2025-04-30."
  • "Plot daily ROAS for portfolio 1234 last month."
  • "What does the latest optimization recommend for portfolio 1234?"
  • "Show attributed conversions per attribution rule for portfolio 1234 in Q1."

The response is real data from your Nexoya workspace, scoped to your user permissions.

Available tools ​

The Nexoya MCP exposes the following tools. Each is callable directly by the AI assistant; you do not invoke them manually.

Account and structure ​

  • list-user-teams

    List all teams where the current user is a member. Returns team ID, name, currency, logo, and number format.

  • list-portfolios — teamId

    List portfolios for a specific team. Returns portfolio ID, team ID, and title.

  • list-portfolio-contents — teamId, portfolioId

    List the contents of a portfolio. Contents are marketing campaigns or adsets, each linked to a provider (Google Ads, Meta, LinkedIn, TikTok, etc.).

  • list-portfolio-funnel-steps — teamId, portfolioId

    List the funnel steps configured for a portfolio. Funnel steps represent stages in the customer journey (impressions, clicks, leads, conversions, revenue).

  • list-portfolio-labels — teamId, portfolioId

    List labels used to categorize and organize contents within a portfolio.

  • list-portfolio-events — teamId, portfolioId, first, after

    List events attached to a portfolio (campaign launches, promotions, market events). Supports pagination via first and after.

Performance and metrics ​

  • get-portfolio-performance — teamId, portfolioId, startDate, endDate

    Aggregate performance metrics for a portfolio over a date range. Returns total spend, funnel step values, cost-per metrics, ROAS, and a per-provider (channel) breakdown. Use this for briefings, ROI analysis, and period comparisons.

  • get-portfolio-daily-metrics — teamId, portfolioId, startDate, endDate

    Daily time-series metrics for a portfolio. Returns one data point per day with spend and funnel step values, broken down by channel. Use this to detect seasonal patterns, structural shifts, and to reason about whether a change is noise or a real trend.

  • get-portfolio-attribution-performance — teamId, portfolioId, startDate, endDate

    Regression-attributed performance broken down by attribution rule. This is Nexoya's model-attributed data (not last-click); the numbers that can be defended to a CFO. Returns attributed and measured funnel step metrics with change percentages per attribution rule.

Optimization ​

  • get-portfolio-latest-optimization — teamId, portfolioId

    The latest optimization for a portfolio. Returns the current budget, the proposed new budget, total spend, and predicted performance for every funnel step (baseline using the current budget vs predicted using the proposed budget).

Example tool call

A typical question routes to multiple tool calls. For "What does the latest optimization recommend for my main portfolio?" Claude will:

  1. Call list-user-teams to find your team ID.
  2. Call list-portfolios to locate the portfolio.
  3. Call get-portfolio-latest-optimization with the resolved IDs.
  4. Summarize the proposed budget changes and predicted lift in plain language.

You do not need to provide IDs manually; the assistant resolves them from names you use in the conversation.

Data and permissions ​

The Nexoya MCP reads data scoped to your user account and team permissions in Nexoya. The MCP currently exposes read-only tools; no destructive actions are performed.

  • Hosting: Data is hosted in the EU / Switzerland under Swiss data protection law and GDPR.
  • Scopes: The OAuth flow requests read access to portfolios, performance, and optimization data within teams you are a member of.
  • Revoking access: Disconnect anytime in Claude → Settings → Connectors, or revoke the OAuth grant in your Nexoya account settings.

Troubleshooting ​

  • OAuth fails or loops — confirm your Nexoya account is active and that you can sign in to app.nexoya.com directly. If your workspace enforces SSO, contact your CSM.
  • No teams or portfolios visible — your user may not be a member of any team, or you may lack permissions on the portfolios you expect to see. Check with your workspace admin.
  • Tool returns "No active optimization found" — the portfolio has no currently running optimization. Trigger one in the Nexoya app and retry.
  • Unexpected provider names — provider mappings are maintained centrally. If a channel shows as "Unknown", report it to support so the mapping can be updated.

Tooling ​

These tools work well alongside the Nexoya MCP for developers building on top of it:

  • Claude.ai

    The primary client for the Nexoya MCP. Connect once and use natural-language queries against your portfolios.

  • MCP Inspector

    Useful for debugging tool calls, inspecting OAuth flows, and testing the MCP server during development.

  • Nexoya GraphQL API

    For programmatic access outside an AI assistant context, the underlying GraphQL API is available directly.

Support ​

For access, technical issues, or feature requests: support@nexoya.com