Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Perspective AI MCP server

Vendor MCP
Open markdown

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

Tools
37
What they doRead · write · destructive
24 · 8 · 524 read8 write5 destructive
Users sign in with
OAuth app
Scalekit's or your own

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 Perspective AI MCP connection

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

    Scalekit credentials are available for Perspective AI 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 = 'perspectiveaimcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Perspective AI 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: 'perspectiveaimcp_agent_template_search',
      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
  • perspectiveaimcp_agent_template_getReturns the full detail of one agent template from the public Agent Library: what it captures, how the conversation runs, the integrations it typically feeds, where it sits in the library, and related templates.Read-only

    Agent Template Get

    Returns the full detail of one agent template from the public Agent Library: what it captures, how the conversation runs, the integrations it typically feeds, where it sits in the library, and related templates. Behavior: - Read-only, public catalog — no workspace is needed. - Unknown slugs return an error; slugs come from agent_template_search. When to use this tool: - You picked an agent template with agent_template_search and want enough detail to describe it to the user or tailor the perspective_create brief. When NOT to use this tool: - You don't have a slug yet — use agent_template_search.

    Inputs

    slugstringrequired
    Agent template slug from agent_template_search.
  • perspectiveaimcp_automation_listLists every automation configured on a perspective with its trigger, channel (sensitive details redacted), execution mode, enabled state, schedule description, and recent error/success metadata.Read-only

    List automations

    Lists every automation configured on a perspective with its trigger, channel (sensitive details redacted), execution mode, enabled state, schedule description, and recent error/success metadata. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - Sensitive parts of channel delivery (e.g., webhook auth headers, full URLs) are redacted before being returned. - has_error / last_error / last_error_at / failure_count appear only when there have been recent failures. When to use this tool: - Auditing what's wired up on a perspective before adding more automations. - Finding an automation_id to feed into automation_update, automation_delete, or automation_test. - Diagnosing a failing automation via last_error / failure_count. When NOT to use this tool: - Creating a new automation — use automation_create. - Toggling enabled or changing config — use automation_update. - Verifying delivery actually works — use automation_test.

    Inputs

    perspective_idstringrequired
    Perspective ID
    workspace_idstringrequired
    Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)
  • perspectiveaimcp_conversations_data_analysisRun a MongoDB aggregation pipeline against conversations for quantitative analysis (counts, distributions, trends, cross-tabs).Read-only

    Conversations data analysis

    Run a MongoDB aggregation pipeline against conversations for quantitative analysis (counts, distributions, trends, cross-tabs). Behavior: - Read-only against a filtered conversation collection (scoped to this perspective). - researchId and mode filters are injected automatically — do not add them. - Max 10 pipeline stages; max 500 result rows. - Only read-only stages are allowed ($match, $group, $sort, $limit, $skip, $project, $unwind, $count, $addFields, $bucket, $bucketAuto, $sortByCount, $facet, $replaceRoot, $replaceWith). When to use this tool: - Exact counts and distributions (referral sources, statuses, tags) - Date-based analysis (conversations per week/month) - Numeric aggregations (average trust scores, message counts) - Cross-tabulations When NOT to use this tool: - Qualitative themes/quotes — use conversations_search (semantic) or conversations_explorer (exact/deep; async + await_job). - Single-conversation transcript — use perspective_get_conversation. - Headline status only — use read_perspective_status or perspective_get_stats.

    Inputs

    perspective_idstringrequired
    Perspective ID (from perspective_list or perspective_create)
    pipelinearrayrequired
    MongoDB aggregation pipeline (array of stage objects). Do NOT include a $match for researchId or mode — those are injected automatically. Example — referral source distribution: [ { "$group": { "_id": "$structuredOutput.referral_source", "count": { "$sum": 1 } } }, { "$sort": { "count": -1 } }, { "$limit": 10 } ] Example — conversations per week: [ { "$group": { "_id": { "$dateToString": { "format": "%Y-W%V", "date": "$created_at" } }, "count": { "$sum": 1 } } }, { "$sort": { "_id": -1 } }, { "$limit": 12 } ]
    titlestringrequired
    Short human-readable label for this query (e.g. "Qualification breakdown", "Weekly signup trend").
    workspace_idstringrequired
    Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)
  • perspectiveaimcp_conversations_explorerStart a deep text exploration of conversation transcripts.Read-only

    Conversations explorer

    Start a deep text exploration of conversation transcripts. Returns immediately with a job_id (status "pending"); long-poll perspective_await_job until status "ready" for findings with source citations. A sub-agent reads raw transcripts (exact phrases, multi-conversation patterns, deep reads). Prefer conversations_search for broad thematic/semantic questions, and conversations_data_analysis for quantitative counts. Omit filters to explore the full analysis corpus. Use filters only to establish a clear transcript boundary: conversation status, a creation-date range, or explicit conversation IDs. Use conversations_data_analysis first when a cohort must be identified from structured attributes, then pass the resulting conversation IDs here. A filtered job covers the complete filtered scope, not the complete perspective. Use for: - Exact mentions of words/phrases - Comparing conversation patterns across time - Reading full conversations with specific participants - Cross-referencing text patterns ("conversations mentioning X AND Y") - Interviewer approach or conversation flow Behavior: - Read-only against conversation data. - Open-world: runs an automated exploration agent in a durable background job using external services. - Each call starts a new job — not safe to retry blindly for the same query. - Typical flow: conversations_explorer → perspective_await_job (re-poll while pending). When NOT to use this tool: - Counts/distributions — use conversations_data_analysis. - Semantic themes without exact match — use conversations_search. - One known conversation id — use perspective_get_conversation. - Polling a previously-started job — use perspective_await_job.

    Inputs

    perspective_idstringrequired
    Perspective ID (from perspective_list or perspective_create)
    querystringrequired
    What to explore in the conversations. Make it discriminative: include the exact phrase, named entity, participant, time window, or comparison. Avoid broad prompts like 'do a full exploration'.
    titlestringrequired
    Short human-readable label for this exploration (e.g. "Compare January vs April conversation patterns").
    workspace_idstringrequired
    Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)
    filtersobject
    Optional raw-corpus filters. Omit to explore the full analysis corpus.
  • perspectiveaimcp_integration_manageRead-only inspector for workspace integrations.Read-only

    Integration Manage

    Read-only inspector for workspace integrations. Operations: "list" enumerates the registered providers (currently slackbot, hubspot, gmail, googledocs, notion, confluence, salesforce, prodege) and connection status; "connect" returns a setup URL the user opens in a browser to complete OAuth, or, for providers connected with customer-issued keys (prodege), a page where the user pastes those keys; "search_tools" returns the available action slugs (e.g., SLACKBOT_SEND_MESSAGE, HUBSPOT_SUBMIT_FORM, GMAIL_SEND_EMAIL) for a connected provider. Behavior: - Read-only. Does NOT itself perform OAuth — "connect" just hands a setup URL back so the user can finish the connection in the web app. - Never ask the user for API keys or secrets in chat — they are only ever entered on the setup_url page. Share the link and ask the user to reply "Done" once saved. - Errors when the workspace is not found or you do not have access. - search_tools returns success: false with "No active <provider> connection. Use 'connect' operation first." when the provider is not connected. Limit is 10 tools per search. - Required params per operation: connect needs provider; search_tools needs provider and query. MCP schema validation rejects missing or unrelated operation arguments before execution; the handler retains equivalent errors for non-MCP callers. When to use this tool: - Checking which integrations the workspace has connected before configuring an automation that talks to one of them. - Surfacing the setup URL to the user when they want to connect a provider. - Discovering action slugs to populate provider-backed automations. When NOT to use this tool: - Creating or modifying automations — use automation_create / automation_update after the provider is connected. - Sending a real message to test a provider wiring — create the automation first, then run automation_test. Examples: - List: `{ "operation": "list" }` - Connect: `{ "operation": "connect", "provider": "slackbot" }` - Search: `{ "operation": "search_tools", "provider": "hubspot", "query": "create contact" }`

    Inputs

    operationstringrequired
    Which inspection to run: "list" enumerates the workspace's registered providers and connection status; "connect" returns a setup URL for a provider; "search_tools" returns the available action slugs for a connected provider.one of listconnectsearch_tools
    workspace_idstringrequired
    Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace whose integrations to inspect.
    providerstring
    The integration provider to target. Required when operation is "connect" or "search_tools"; ignored when operation is "list".one of slackbothubspotgmailgoogledocsnotionconfluencesalesforceprodege
    querystring
    Search text used to find matching action slugs for the given provider. Required when operation is "search_tools"; ignored otherwise.
  • perspectiveaimcp_perspective_await_jobLong-polls an async job and returns either its terminal result or another "pending" envelope to keep polling.Read-only

    Await job

    Long-polls an async job and returns either its terminal result or another "pending" envelope to keep polling. Supported jobs (started by these tools): - Perspective design — perspective_create / perspective_respond / perspective_update - Conversations explorer — conversations_explorer - Conversation import — perspective_import_conversation Behavior: - Read-only — observes a running job. Safe to call repeatedly. - Errors with "Unknown job_id" if no such job exists, or if the id is not a supported job kind. Workspace and perspective access are re-checked on every call. - Each call blocks up to wait_ms (default 30s, min 1s, max 45s). On timeout, returns status "pending" with a progress_cursor — pass it back on the next call to skip already-seen progress events. - Terminal status: - "ready" = job finished successfully (design: outline ready; explorer: answer + sources; import: conversation_id — discriminate via job_kind) - "needs_input" = design-only follow-up question - Failures are logged with the underlying workflow detail but surfaced as a generic "The job failed. Please try again." to avoid leaking internals. When to use this tool: - Immediately after a start tool returns a job_id. - Re-polling after a previous call returned status "pending" (pass the returned progress_cursor back). When NOT to use this tool: - You don't have a job_id yet — call the start tool first. - Inspecting a finished perspective's config — use perspective_get.

    Inputs

    job_idstringrequired
    Job ID returned by perspective_create, perspective_respond, perspective_update, conversations_explorer, or perspective_import_conversation
    progress_cursorinteger
    Resume the progress stream at this chunk index. Use the value returned in the previous pending response to avoid duplicate progress notifications.
    wait_msinteger
    Long-poll duration in milliseconds (default 30000, max 45000)default 30000
All 62 in Automation