MCP server

Connect

The server URL is http://localhost:3000/api/mcp (Streamable HTTP). Apps that support signing in (ChatGPT, Claude) connect without a key; the rest use an API key.

With an API key (Claude Code, Cursor, VS Code, Claude Desktop): create one in Integrations → API & automations and use it in your client:

claude mcp add --transport http huginnova http://localhost:3000/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "huginnova": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "huginnova": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "huginnova": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/api/mcp",
        "--header",
        "Authorization:${AUTH}"
      ],
      "env": {
        "AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Authentication

Two ways, both as Authorization: Bearer …: an OAuth connection (apps that sign in) or an API key. Read-only connections and keys can use every read tool; full access also allows the change tools. The MCP server is included in every plan. Limit: 120 requests a minute per connection or key.

OAuth, for developers

OAuth 2.1 as the MCP authorization spec describes it. A request without a token gets a 401 whose WWW-Authenticate header points to the protected resource metadata; from there, the authorization server metadata at /.well-known/oauth-authorization-server. Apps identify themselves with a Client ID Metadata Document (an https client_id) or register with Dynamic Client Registration. Authorization code with PKCE (S256) only, and the resource must be the MCP server URL. Scopes: read and write (the person can grant less than asked). Access tokens last an hour; refresh tokens rotate on every use, and reusing an old one closes the connection.

Prompts

Ready-made questions your client shows in its menu ("/" in Claude), in your workspace's language. Brand and competitor names autocomplete as you type; the brand is optional if you track only one.

• weekly_report

  Weekly AI visibility report: where you stand, what changed and why, priorities.

• what_to_do_this_week

  What to do this week: the three changes most likely to get you into more AI answers.

• why_competitor_wins

  Why a competitor wins: the real answers and sources behind it, and what to change.

How results work

Pages. Lists return items, total and next_cursor. Pass next_cursor back as cursor for the next page; it's null on the last one. Newest-first lists (answers, alerts) use the row's date and id, so new rows arriving while you page never repeat or skip any.

Summaries and detail. search_answers returns a short summary per answer (engine, prompt, date, brands named and positions, domains cited, the passage about you). Read one in full with get_answer; articles work the same way with list_articles and get_article.

Rates. Visibility, citation and similar rates are shares of answers from 0 to 1, with a 95% confidence interval. Small samples are uncertain: changes are marked as significant or not.

Format. Each result is returned as JSON text and as structuredContent. Errors you can fix (a bad argument, a plan limit, something not found) come back as tool errors with the reason.

Example questions

• “How visible is my brand in AI answers this month, and against whom?”
• “Why does ChatGPT recommend my main competitor and not us? Show me the answers.”
• “Which sites should I get mentioned on first, and what do they say?”
• “What changed since last week, and what should I do about it?”
• “Add these five questions to the prompts I track.”
• “Mark the structured-data fix as done.”

Security

Connections and keys belong to one workspace and only see its data. The server never starts paid work (collections, articles, emails): those stay in the app. Disconnect an app or revoke a key in Integrations at any time; it stops working immediately, and a person who leaves the workspace loses the apps they connected.