Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Motion MCP server

Vendor MCP
Open markdown

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

Tools
14
What they doRead · write · destructive
13 · 1 · 013 read1 write0 destructive
Users sign in with
OAuth app
Scalekit's or your own

What you can do

  • Analyze ad creatives: pull performance insights, AI summaries, and video transcripts for your own ad creatives
  • Break down results: view ad performance by age and gender and open saved reports
  • Research competitor brands: search brands, list tracked competitors, and browse their creatives by date, format, or platform
  • Get brand context: retrieve brand positioning, voice, messaging angles, and customer voice analysis

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 Motion MCP connection

    In AgentKit > Connections, create a Motion MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Motion MCP server, so you don't need to register an OAuth app.

  4. 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 = 'motionmcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Motion 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: 'motionmcp_get_auth_context',
      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
  • motionmcp_get_auth_contextRetrieve the authenticated user's organizations and workspaces.Read-only

    Get Auth Context

    Retrieve the authenticated user's organizations and workspaces. Returns the workspaceId required by all other Motion tools.

    Inputs

    This tool takes no inputs.

  • motionmcp_get_brand_by_domainResolve a brandId from a website domain or URL.Read-only

    Get Brand By Domain

    Resolve a brandId from a website domain or URL. Returns null if no brand is found for the given domain.

    Inputs

    brandUrlstringrequired
    Brand URL or domain, for example `https://example.com`
    workspaceIdstringrequired
    The workspace ID for authorization
  • motionmcp_get_creative_insightsRetrieve creative performance insights for your own ads in a workspace.Read-only

    Get Creative Insights

    Retrieve creative performance insights for your own ads in a workspace. Either datePreset or both startDate and endDate must be provided.

    Inputs

    insightTypestringrequired
    Primary metric to sort/rank creatives byone of SPENDSCALINGHOOKROASPURCHASESPURCHASE_VALUECTR_ALLCPACPC
    organizationIdstringrequired
    The organization ID from get_auth_context
    workspaceIdstringrequired
    The workspace ID from get_auth_context
    chartKPIsarray
    Optional KPI fields to include in chart KPI metrics.
    creativeAssetIdsarray
    Optional creative asset IDs to narrow results.
    datePresetstring
    Predefined date range. Omit if using startDate/endDate.one of TODAYYESTERDAYTHIS_MONTHLAST_MONTHLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_90_DAYSCUSTOM
    endDatestring
    Custom end date (YYYY-MM-DD). Requires datePreset=CUSTOM.
    filtersarray
    Nested filter groups to narrow which creatives are returned. Outer array = AND (all groups must pass); inner array = OR (any filter in a group can match). For text fields (campaignName, adsetName, adName): use "value" (singular) for case-insensitive substring match, or "values" (array) for exact match. For metric fields: set "metric": true and use "value" for thresholds or "values" for ranges. Example: [[{"field":"spend","type":"GREATER_THAN","value":"100","metric":true}],[{"field":"campaignName","type":"includes","value":"Prospecting"}]] returns creatives where spend > 100 AND campaign name contains "Prospecting".
    groupBystring
    How to group ranked rows. Options: 'creative' (default — one row per creative asset), 'adId' (one row per ad — for ad-level optimization, comparing same creative across ad sets, deciding which ad to pause/scale), 'name' (by ad name), 'copy' (by ad body text — 'which copy performs best?'), 'headline' (by headline text), 'landingPage' (by destination URL — 'which landing page converts best?').one of creativeadIdnamecopyheadlinelandingPage
    includeEntityCategoryValuesboolean
    Include the full taxonomy catalog (all possible values) per glossary category. Default false — only the values applied to each creative are returned. Set true when you need to see all available tags for coverage gap analysis.default false
    includeGlossaryboolean
    Include creative taxonomy/glossary tags per creative. Default false to minimize payload. Set true for creative pattern analysis.default false
    insightGroupsarray
    Metric groups per creative. Defaults: spendState, performance, motion, click.
    limitinteger
    Max number of creatives to return
    startDatestring
    Custom start date (YYYY-MM-DD). Requires datePreset=CUSTOM.
    tableKPIsarray
    Optional KPI fields to include in table KPI metrics.
    withAggregatedInsightsboolean
    Include account-level aggregated metricsdefault false
  • motionmcp_get_creative_summaryFetch a compact AI-generated summary for a specific creative asset in a workspace.Read-only

    Get Creative Summary

    Fetch a compact AI-generated summary for a specific creative asset in a workspace.

    Inputs

    creativeEntityIdstringrequired
    Mongo ObjectId of the creative entity
    creativeFormatstringrequired
    Creative format from the source tool. Pass through the source value; `unknown` may fail if no compatible summary prompt exists.one of videoimageunknown
    creativeOriginstringrequired
    Source/origin of the creativeone of metaCreativeAssettiktokCreativeAssetyoutubeCreativeAssetlinkedinCreativeAssetmetaAdLibraryCreativetiktokAdLibraryCreativeinstagramAdLibraryCreativetiktokOrganicAdLibraryCreative
    organizationIdstringrequired
    The organization ID from get_auth_context
    workspaceIdstringrequired
    The workspace ID from get_auth_context
  • motionmcp_get_creative_transcriptFetch the spoken transcript for a video creative by its entity ID and workspace.Read-only

    Get Creative Transcript

    Fetch the spoken transcript for a video creative by its entity ID and workspace.

    Inputs

    creativeEntityIdstringrequired
    Mongo ObjectId of the creative entity
    creativeOriginstringrequired
    Source/origin of the creativeone of metaCreativeAssettiktokCreativeAssetyoutubeCreativeAssetlinkedinCreativeAssetmetaAdLibraryCreativetiktokAdLibraryCreativeinstagramAdLibraryCreativetiktokOrganicAdLibraryCreative
    workspaceIdstringrequired
    The workspace ID from get_auth_context
    creativeFormatstring
    Creative format (video or image). Transcript data is only available for video creatives; image creatives will return empty transcript data.one of videoimagedefault video
  • motionmcp_get_glossary_valuesReturn the workspace's glossary taxonomy — categories and their allowed tag values.Read-only

    Get Glossary Values

    Return the workspace's glossary taxonomy — categories and their allowed tag values.

    Inputs

    workspaceIdstringrequired
    The workspace ID
    categoryNamesarray
    Optional list of glossary category internal names
    customOnlyboolean
    Return only custom glossary categoriesdefault false
    includeCreativeIdsboolean
    Include creative IDs in value bucketsdefault false
  • motionmcp_get_inspo_brand_contextRetrieve strategic brand context for an Inspo brand, including positioning, voice, tone, messaging angles, and customer voice analysis.Read-only

    Get Inspo Brand Context

    Retrieve strategic brand context for an Inspo brand, including positioning, voice, tone, messaging angles, and customer voice analysis.

    Inputs

    brandIdstringrequired
    The brand ID to get Inspo context for
    workspaceIdstringrequired
    The workspace ID for authorization
  • motionmcp_get_inspo_creativesRetrieve Inspo creatives for one or more brands by brand ID, with optional filters for date range, format, and platform.Read-only

    Get Inspo Creatives

    Retrieve Inspo creatives for one or more brands by brand ID, with optional filters for date range, format, and platform.

    Inputs

    brandIdsarrayrequired
    One or more brand IDs to fetch Inspo creatives for
    launchDatestring
    Optional launch date window. When omitted, returns creatives regardless of launch date. Available: LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS.one of LAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_90_DAYS
    limitinteger
    Max creatives to return. Defaults to 50. For larger pulls, increase up to 1000.default 50
    sortstring
    Sort order by launch dateone of NEWESTOLDESTdefault NEWEST
    statusstring
    Optional ad status filterone of ACTIVEINACTIVEACTIVE_AND_INACTIVE
    withGlossaryboolean
    Include Motion glossary tags for returned creativesdefault false
All 40 in Project Management