Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Calven MCP server

Vendor MCP
Open markdown

The Calven MCP connector routes your AI agent's tool calls to Calven's own MCP server through Scalekit. Each user signs in to Calven once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 16 tools.

Tools
16
What they doRead · write · destructive
13 · 3 · 013 read3 write0 destructive
Users sign in with
OAuth app
Your own Calven MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Calven MCP connection

    In AgentKit > Connections, create a Calven MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Calven MCP server connections use your own OAuth app. Register one with Calven MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Calven MCP connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'calvenmcpoauth'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Calven MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'calvenmcpoauth_get_competitor',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • calvenmcpoauth_get_competitorOne competitor in a single call: the row, its battlecard (how to sell against them: traps, objections, proof points), its most recent competitive signals, and the outline of its deep-dive dossier (pricing, packaging, positioning, strengths, weaknesses) with the call that reads the dossier whole.Read-only

    Get competitor

    One competitor in a single call: the row, its battlecard (how to sell against them: traps, objections, proof points), its most recent competitive signals, and the outline of its deep-dive dossier (pricing, packaging, positioning, strengths, weaknesses) with the call that reads the dossier whole. Use when: a question names a specific rival, including how they price, package, position or sell. Competitor pricing lives in their dossier, not in any product brief: read it with the read_document call the result prints. Do NOT use when: you want the whole roster or a filtered feed: list_records({ kind: "competitors" }) and list_records({ kind: "competitive_signals" }) do that. Args: Pass `id` or `name`, not both. Returns: competitor { id, name, cells, battlecard, recent_signals, signals_has_more, deep_dive { asset_id, word_count, sections } }. A null battlecard or deep_dive is not published; the notes say which documents are. Example: get_competitor({ name: "Collibra" })

    Inputs

    idstring
    The 8-character id shown in results, or a full id.
    namestring
    The competitor name, case-insensitive. Use instead of `id`.
  • calvenmcpoauth_get_insight_detailThe rows behind one number on an Insights dashboard: the deals in a pricing bucket or loss outcome, the deals against one competitor, what buyers answered to one survey question, one AI assistant answer, the market-signal feed.Read-only

    Get insight detail

    The rows behind one number on an Insights dashboard: the deals in a pricing bucket or loss outcome, the deals against one competitor, what buyers answered to one survey question, one AI assistant answer, the market-signal feed. Use when: get_insights returned a number and you need its evidence. Sections name the drill-downs they support under "Rows behind these numbers". Args: detail is one of win_loss.verbatims, win_loss.answers, win_loss.pricing_deals, win_loss.product_deals, win_loss.loss_outcome_deals, competitive_intelligence.competitor_deals, competitive_intelligence.pricing_deals, positioning.ai_answer, market_research.signals. Pass the same product and window as the get_insights call it drills into. verbatims needs group, answers needs question (a question_id), product_deals needs product. Other arguments narrow where they apply; leave verdict, bucket or outcome out to get every group, labelled. Returns: items[] (at most `limit`, max 100) and more_available with how to narrow. Deal names, amounts and buyer survey answers follow the workspace security settings. Example: get_insight_detail({ detail: "competitive_intelligence.competitor_deals", competitor: "AuditBoard", outcome: "lost" })

    Inputs

    detailstringrequired
    Which drill-down.one of win_loss.verbatimswin_loss.answerswin_loss.pricing_dealswin_loss.product_dealswin_loss.loss_outcome_dealscompetitive_intelligence.competitor_dealscompetitive_intelligence.pricing_dealspositioning.ai_answermarket_research.signals
    answerstring
    ai_answer: an assistant's name (e.g. ChatGPT) or an answerId. Omit for every assistant's latest answers.
    bucketstring
    loss_outcome_deals: what beat us. Omit for every bucket, each row labelled.one of competitorin_houseno_decisionunattributed
    competitorstring
    CI details: one competitor, by name.
    fromstring
    First day counted, YYYY-MM-DD. Pass `to` with it.
    groupstring
    verbatims: a survey group with written answers, e.g. "Product".
    include_untaggedboolean
    With `product`: also count rows with no product tag (company-wide, or not yet tagged).default false
    limitinteger
    Rows to return, default 20, max 100.
    loss_reasonstring
    competitor_deals: one loss reason.
    monthstring
    competitor_deals: YYYY-MM.
    offsetinteger
    Rows to skip: the `next rows: offset` a previous reply printed.
    outcomestring
    Omit for both, each row labelled.one of wonlost
    productstring
    Product name (case-insensitive, as list_products prints it) or id: only rows tagged with it, like the dashboard's product chip. "untagged" alone: only rows with no product. Omit for the whole company.
    questionstring
    answers: a question_id.
    ratinginteger
    answers: one rating.
    tierinteger
    CI details: one tier of rivals, as the HTTP drill-down takes it: 1, 2 or 3 (the pricing_distribution pool tier_N), "emerging" or "untiered". Accepts 1, 2 or 3 (as a number) or "emerging" or "untiered".
    timeframestring
    Today is 2026-11-14. trailing4w / trailing12m (default) = this week / month so far plus the 3 / 11 before; thisQuarter, thisYear = so far; lastMonth, lastQuarter, lastYear = the previous complete one. Any other month or quarter ("Q2"): from + to.one of trailing4wtrailing12mthisQuarterthisYearlastMonthlastQuarterlastYear
    tostring
    Last day counted, YYYY-MM-DD (August 2026 = 2026-08-01 to 2026-08-31).
    verdictstring
    pricing_deals: less_expensive|on_par|more_expensive (win_loss), cheaper|on_par|pricier (CI). Omit for every verdict, each row labelled.
  • calvenmcpoauth_get_insightsAny agent's Insights dashboard as data: the numbers each section of the tab shows (KPIs, rates, breakdowns, trends, rankings), computed exactly as the dashboard computes them.Read-only

    Get insights

    Any agent's Insights dashboard as data: the numbers each section of the tab shows (KPIs, rates, breakdowns, trends, rankings), computed exactly as the dashboard computes them. Each comparable KPI comes with its change against the period before. Use when: a question is about totals, rates, shares, trends or rankings, or any KPI tile (the `sections` parameter lists the tiles of each section): win rate, why we lose, which segment sells best (win_loss segments), ICP vs non-ICP pipeline, product gaps that cost deals, competitor momentum, customer themes, messaging drift, how AI describes us. Do NOT use when: "how are we doing" or a periodic review across dashboards (get_insights_overview first); the individual rows behind a number (get_insight_detail, or list_records); a strategy document (get_strategy_document). Args: dashboard + optional sections (omit for every section). Window: timeframe OR from+to (both days counted), default trailing12m; positioning and messaging have no window. product: strict, like the dashboard chip. Returns: sections[] { id, title, status, data, notes, placeholders }, the window counted and the period it is compared with, the product scope, and a link to the dashboard. A KPI's `comparison` is { prior, delta, prior_n } (delta in percentage points for rates), or { reason } when it cannot be compared (never read that as no change); a KPI marked snapshot is current state, with no change; a KPI marked not_compared counts the period but has no change on purpose (it is still filling in or reads today's state), so never compute one from other periods. Placeholders are widgets with no numbers behind them: say there is no number, never estimate one. Cite the sample (n) beside every rate. Example: get_insights({ dashboard: "competitive_intelligence", sections: ["performance"], timeframe: "thisQuarter" })

    Inputs

    dashboardstringrequired
    Which Insights tab. win_loss: win rate, pipeline won/lost, why we win and lose, segments; win_loss_program_health: the survey program; competitive_intelligence: per-competitor performance, battlecards, influenced revenue; icp: ICP fit, win predictors; voice_of_customer: customer themes, signals, quotes; persona: buying group, multi-threading; positioning and messaging: consistency, drift, AI perception; market_research: opportunities, trends, signals; product_intelligence: product gaps that cost deals, drift.one of win_losswin_loss_program_healthcompetitive_intelligencevoice_of_customericppersonapositioningmessagingmarket_researchproduct_intelligence
    fromstring
    First day counted, YYYY-MM-DD. Pass `to` with it.
    include_untaggedboolean
    With `product`: also count rows with no product tag (company-wide, or not yet tagged).default false
    liststring
    With one section: the rest of a list a reply cut, by the name its header prints ("next rows: list: …"), 200 rows from `offset`.
    offsetinteger
    With `list`: rows to skip, as the cut header prints.
    productstring
    Product name (case-insensitive, as list_products prints it) or id: only rows tagged with it, like the dashboard's product chip. "untagged" alone: only rows with no product. Omit for the whole company.
    sectionsarray
    Omit for all, or ids to read only those ([KPI tiles], * no numbers): win_loss: scoreboard [Competitive win rate,Pipeline won,Pipeline lost,Sentiment],segments,buying_group,surveys_head_to_head,surveys_product,surveys_pricing_legal,surveys_sales_team,why_won_lost,deciding_forces; win_loss_program_health: scoreboard [Deals with completed win-loss,Completion rate,AI interview vs. online survey],volume,email_delivery [Bounce rate,Emails sent],response_funnel,ai_interviews [Picked the AI interview,Rated the AI interview good],respondent_experience [Rated the online survey good],enrollment_coverage [Deals enrolled,Deals analyzed],segment_coverage,timing [Median AI interview length,Median online survey time,Started but not finished]; competitive_intelligence: kpis [Competitive win rate,Influenced revenue,Battlecard coverage,Competitors in catalog],performance,showdown,market_movement [Feature parity coverage*,"Bullshit detector" flags*]; voice_of_customer: kpis [Conversations analyzed,Customer-voice signals,Product feedback signals,Analyst-hours saved],customer_signals,tied_to_revenue,quotes; icp: kpis [ICP share of wins,ICP-fit pipeline,Avg deal size,Sales cycle],expand_icp,win_predictors,reality_check; persona: kpis [Multi-threading win-rate,Single-threaded pipe,Multi-threaded pipe,Contact coverage],buying_group,persona_intelligence,keeping_honest; positioning: kpis [Positioning alignment,Drift resolved,Positioning moves],consistency,market_landscape [Perceptual map*,Differentiator defensibility*],grounded,ai_perception; messaging: kpis [Message sharpness,Customer-language fit,Messaging alignment,Evidence-backed pillars],effectiveness,quality,customer_language,field_adoption; market_research: kpis [Opportunities surfaced,Opportunities actioned,High-impact trends,Signals tracked],opportunities_trends,signal_intelligence; product_intelligence: kpis [Drift flagged,Assets synced,Unsupported claims*,Enablement coverage*],product_changes [Strengths vs gaps*,Product claims feed*],outcomes
    timeframestring
    Today is 2026-11-14. trailing4w / trailing12m (default) = this week / month so far plus the 3 / 11 before; thisQuarter, thisYear = so far; lastMonth, lastQuarter, lastYear = the previous complete one. Any other month or quarter ("Q2"): from + to.one of trailing4wtrailing12mthisQuarterthisYearlastMonthlastQuarterlastYear
    tostring
    Last day counted, YYYY-MM-DD (August 2026 = 2026-08-01 to 2026-08-31).
  • calvenmcpoauth_get_insights_overviewEvery Insights dashboard's headline KPIs for one window, each comparable one with its change against the period before, plus what moved most in each ranked list, the current top loss reasons and product gaps, and which dashboards have no data.Read-only

    Get insights overview

    Every Insights dashboard's headline KPIs for one window, each comparable one with its change against the period before, plus what moved most in each ranked list, the current top loss reasons and product gaps, and which dashboards have no data. Use when: "how are we doing", a monthly or quarterly review, a launch readout (with product), or one headline KPI. Each item names the get_insights section to read next. Do NOT use when: a breakdown, trend or longer ranking (get_insights; a long list says how many it shows of the total). Args: product and the window, as get_insights. Returns: kpis[] with `comparison` (as get_insights), movers[], top_loss_reasons, product_gaps (amount_at_risk covers won and lost deals: not lost revenue), availability, window and compared period. Example: get_insights_overview({ timeframe: "lastMonth" })

    Inputs

    fromstring
    First day counted, YYYY-MM-DD. Pass `to` with it.
    include_untaggedboolean
    With `product`: also count rows with no product tag (company-wide, or not yet tagged).default false
    productstring
    Product name (case-insensitive, as list_products prints it) or id: only rows tagged with it, like the dashboard's product chip. "untagged" alone: only rows with no product. Omit for the whole company.
    timeframestring
    Today is 2026-11-14. trailing4w / trailing12m (default) = this week / month so far plus the 3 / 11 before; thisQuarter, thisYear = so far; lastMonth, lastQuarter, lastYear = the previous complete one. Any other month or quarter ("Q2"): from + to.one of trailing4wtrailing12mthisQuarterthisYearlastMonthlastQuarterlastYear
    tostring
    Last day counted, YYYY-MM-DD (August 2026 = 2026-08-01 to 2026-08-31).
  • calvenmcpoauth_get_personaOne persona's row plus its deep-research canvas: pains, gains, jobs to be done, objections, messaging hooks.Read-only

    Get persona

    One persona's row plus its deep-research canvas: pains, gains, jobs to be done, objections, messaging hooks. Use when: you are tailoring copy, a play or an objection response to a specific persona. Do NOT use when: you want the roster of personas: list_records({ kind: "personas" }) is the lightweight read. Args: Pass `id` or `name`, not both. Returns: persona { id, name, cells, canvas }. A null canvas means no canvas is published; the row attributes still apply. Example: get_persona({ name: "VP of Data" })

    Inputs

    idstring
    The 8-character id shown in results, or a full id.
    namestring
    The persona name, case-insensitive. Use instead of `id`.
  • calvenmcpoauth_get_recordOne row with its FULL cell set.Read-only

    Get record

    One row with its FULL cell set. Each list_records result names the columns get_record would add; when it says none, the list line already had everything. Use when: you have a row id (or an exact name) and need everything the workspace knows about it. Do NOT use when: the row is a competitor or a persona: get_competitor and get_persona add its documents. Args: Pass one of `id`, `name` or `ids`. `id` is the short `id:` a list_records line prints (8 characters), or the full id. `name` is the exact name or title (case-insensitive); quotes, findings, drivers and claims go by id. `ids`: up to 25 rows of one kind in one call, never one call per row. Returns: record { id, kind, name, cells }, or records[] with `ids`. Agent-only bookkeeping columns are never included. Example: get_record({ kind: "trends", name: "AI governance" })

    Inputs

    kindstringrequired
    Which curated database the row belongs to.one of competitorscompetitive_signalspersonastrendsmarket_opportunitiesanalyst_findingsthemesquotesvendor_quotescustomer_conversationsmarket_signalsdeal_driversproduct_changesproduct_drift_findingsclaimssurveyed_dealssurvey_responsescrm_accountscrm_contactscrm_deals
    idstring
    The 8-character id a list_records line prints, or a full id.
    idsarray
    Several rows of this kind at once, by the ids list_records prints. Use instead of `id`.
    namestring
    The exact row name, case-insensitive. Use instead of `id`.
  • calvenmcpoauth_get_strategy_documentOne of the four workspace strategy documents, as published markdown.Read-only

    Get strategy document

    One of the four workspace strategy documents, as published markdown. positioning = category, target, differentiation, narrative. messaging = value props, pillars and approved wording. product_brief = what the product does, its features, packaging, PRICING and plans. icp = who it is for. Use when: you are writing or checking anything that must match this company's position, wording, product truth or target. Our own pricing, plans or packaging: read product_brief. A competitor's pricing: get_competitor. Why deals were won or lost: get_insights (dashboard win_loss) for the totals, then list_records on surveyed_deals, survey_responses or deal_drivers. Do NOT use when: you want a competitor dossier, a battlecard or a persona canvas: use get_competitor, get_persona, or list_documents plus read_document. Args: `product` scopes to that product's instance; if it has none, the company-wide document comes back with `scope.product` null and a note, and it still applies. Returns: document { asset_id, kind, name, product, version, word_count, sections[], content, part? } or null when nothing has been published. A document longer than one reply comes in parts: the reply names the call for the next part. Example: get_strategy_document({ document: "icp", product: "Billing" })

    Inputs

    documentstringrequired
    Which strategy document to read.one of positioningmessagingproduct_brieficp
    offsetinteger
    Only for a document longer than one reply: the parts (H2 sections) to skip, i.e. the `offset` in the "Next part" call the previous reply printed. Omit to start at the top.
    productstring
    Product name, e.g. "Billing" (case-insensitive; an id also works). Returns that product's own version of the document, or the company-wide one with a note when it has none. Without it: the company-wide document. A wrong name returns the valid names; so does list_products.
  • calvenmcpoauth_get_taskThe status of a background task you started, and its result once it finishes.Read-only

    Get task

    The status of a background task you started, and its result once it finishes. Use when: you hold a task_id from review_against_personas, ask_the_market or ask_about_competitor and are waiting for the result. Args: Poll while status is "working", waiting as long as the start verb said (poll_after_seconds). Returns: working (still running), input_required (waiting on a human in the app), completed (result is in `result`), failed (reason is in `error`). Example: get_task({ task_id: "…" })

    Inputs

    task_idstringrequired
    The task_id a start verb such as review_against_personas or ask_the_market returned: the 8-character id it printed, or a full id.