انتقل إلى المحتوى الرئيسي

MCP integration

For modular organizations, the connected organization needs an active CRM module as well as the integration's required scopes. The underlying API returns HTTP 403 with module_not_active when CRM access is unavailable. Resolve module access in Subscription before retrying; changing the API key alone does not fix this error.

Scoutello provides a remote Model Context Protocol (MCP) server for controlled access to organization data. It uses the same integrations, API keys, scopes, tenant checks, rate limits, and record behavior as the Scoutello REST API.

Use MCP when an AI client or agent should discover and call Scoutello operations as tools. Use REST when an application needs conventional HTTP endpoints or a generated OpenAPI client. Both surfaces use the same underlying data contract.

Before connecting​

An organization administrator must create an integration in Organization settings → Developer/API. When creating or rotating its key:

  1. Select only the read and write scopes the MCP client needs.
  2. Save the complete sctl_api_ key when it is shown. Scoutello displays it once.
  3. Store the key in the MCP client's secret or environment configuration, not in source control.

The same integration key can call REST and MCP. Creating a second MCP-specific key is neither required nor recommended. Former sctl_mcp_ keys are not accepted.

Connection values​

Configure the client with these values:

Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the saved integration key. Client configuration formats differ, but the transport, URL, and HTTP header above stay the same. If a client cannot set Authorization, it may send the key in x-api-key instead. Do not configure both headers.

The legacy https://admin.scoutello.com/api/mcp URL remains a compatibility alias. New connections should use the versioned /api/v1/mcp endpoint.

Verify the connection​

After the client connects, call the whoami tool first. It returns the current integration and organization, credential expiry and usage information, rate-limit state, and granted scopes without exposing organization records.

If whoami identifies an unexpected organization or integration, disconnect the client and correct its key before calling another tool.

Tools and scopes​

The MCP server only advertises tools granted by the current key. A client cannot discover or call a write tool using only the corresponding read scope.

API scopeMCP tools
contacts.readcontacts_list, contacts_get, contacts_get_by_external_id
contacts.writecontacts_batch_upsert
tasks.readtasks_list, tasks_get, tasks_get_by_external_id
tasks.writetasks_batch_upsert
protocols.readprotocols_list, protocols_get, protocols_get_by_external_id
protocols.writeprotocols_batch_upsert
opportunities.readopportunities_list, opportunities_get, opportunities_get_by_external_id
opportunities.writeopportunities_batch_upsert
projects.readprojects_list, projects_get, projects_get_by_external_id
projects.writeprojects_batch_upsert (including participant upserts)
milestones.readmilestones_list, milestones_get, milestones_get_by_external_id
milestones.writemilestones_batch_upsert
members.readmembers_list
events.readevents_list, events_get, events_get_by_external_id
events.writeevents_batch_upsert
mails.readmails_list, mails_get
mail-drafts.readmail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id
mail-drafts.writemail_drafts_batch_upsert (prepare for human review only)
tags.readtags_list
scrape-jobs.readscrape_jobs_list, scrape_jobs_get
scrape-jobs.writescrape_jobs_create, scrape_jobs_import, scrape_jobs_cancel
inbound-mails.readinbound_mails_list, inbound_mails_get

whoami is always available to an authenticated connection. Tool inputs and results follow the same schemas and response envelopes as their linked REST operations.

contacts_list accepts bounded search across first/last/company names, type, status, and tagIds (an array of 1–50 IDs, matching any selected tag). All search tokens must match a name field; all filters combine with AND. Carry these filters through every cursor page. For example, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } finds matching existing accounts without scanning the full inventory.

Nonmember CRM contacts linked to a Scoutello login are readable and referenceable, while membership/account fields remain hidden and contact edits stay protected. An external-link-only upsert can register a readable contact using externalId, its scoutelloId, and optional externalUpdatedAt; omit all CRM fields. Later retries/metadata updates omit scoutelloId. See the contact boundary and linking rules.

Write safely​

Batch-upsert tools can change Scoutello data immediately. They are idempotent for the same integration and external IDs, but callers should still review the intended resource, organization, and scope before applying changes.

Set mode to validate to run matching and validation without writing. After inspecting the results, repeat the call with mode: "apply" to accept valid records. MCP does not expose delete operations.

Pausing an integration rejects both REST and MCP requests using its keys. Rotating replaces its credential, and revoking permanently disables every credential belonging to the integration.

Troubleshooting​

ResultWhat to check
401 authentication errorConfirm that the complete key is present and the header uses Bearer, with no quotes around the key.
403 authorization errorGrant the required scope by rotating the integration key, then update the client with the replacement key.
404 at the MCP URLConfirm the URL ends in /api/v1/mcp. The MCP service may not yet be enabled in that Scoutello environment.
429 rate-limit errorWait until the returned reset time before retrying. REST and MCP consume the same integration quota.
Tool is missingCheck the key's scopes with whoami; unavailable tools are intentionally omitted from discovery.

For record fields, pagination, batch behavior, and error envelopes, continue with the Scoutello API reference.

Connected project planning​

Create a project, then its milestones, then tasks and protocols using stable integration external IDs. New milestone access requires milestones.read/milestones.write; grant members.read to look up assignable members. Existing credentials are not automatically broadened. After rotating/granting access, refresh tool discovery and inspect whoami.

Use member Customer IDs for project/milestone assignedContacts, and User IDs for task assignedScoutelloUserIds or opportunity ownerScoutelloUserId. Task/protocol references accept projectScoutelloId or projectExternalId, plus the equivalent milestone/opportunity pairs. Milestone-only links infer the project; mismatches reject the batch item. Project participants are additive upserts and preserve omitted entries.

Protocols support contactless project/milestone notes and draft/final status. Imports of this connected work are silent and never send communications. List tools expose the same entity-specific project, status, assignment, and due-date filters as REST. Carry the exact filters, including updatedSince, through each cursor page. See the API reference for the complete contract and null/omitted semantics.

Validate each dependent batch, apply it, inspect every result, and read back the records before treating population as complete. A dry run cannot resolve parents that only exist in another dry run. When retrying an ambiguous initial link using scoutelloId, first read by external ID; bootstrap IDs cannot be replayed once the link exists.

Sales-project agent instructions​

External sales agents and contact discovery​

Grant scrape-jobs.read/scrape-jobs.write to discover contacts using the existing scraper. scrape_jobs_create accepts a stable requestId, query, source (firecrawl or google_maps), optional geographic scope, and a bounded candidateLimit (default 5, maximum 20). For project work, pass projectId and participantGroupId; use projects_get to discover the project's group IDs. Read progress and candidates with scrape_jobs_get, then use scrape_jobs_import with stable selectedCandidateIds and mode: "validate" before applying. Import also requires contacts.read, contacts.write, and projects.write. An omitted or empty selection imports nothing. The external agent decides fit; scraper relevance scores are advisory and do not override explicit selection. Creating a project-targeted job requires projects.read.

Imports reuse existing contacts without overwriting their CRM fields. They add missing participation, preserve existing different groups, and return individual receipts for ambiguous identities, deleted/protected contacts, and group conflicts. Membership is distinct from eligibility for outreach. Use contacts_list with projectScoutelloId and groupScoutelloId to read the target cohort; project filters require projects.read. Carry all filters through cursor pages.

With inbound-mails.read, inbound_mails_list and inbound_mails_get retrieve incoming messages and their text. The default is the organization inbox. Personal messages remain restricted to the acting member. To prepare a threaded response, set inReplyToInboundMailScoutelloId on a mail_drafts_batch_upsert record. Scoutello derives and freezes the recipients and threading headers for review. replyTo is a return address, not a reference to the message being answered.

Run sales agents in an externally managed sandbox. Scoutello supplies the MCP tools and durable records; the external agent owns research, candidate assessment, outreach planning, retries, follow-up timing, and reply interpretation. Scoutello does not create or run acquisition campaigns.

A typical agent run is:

  1. Call whoami, then read the project, relevant contacts, and communication history.
  2. Start a bounded scrape_jobs_create request with a stable requestId.
  3. Poll scrape_jobs_get for progress and inspect each candidate's evidence and stable ID. Scraping results are candidates; the agent decides whether they fit.
  4. Record source-backed assessment in project protocols or tasks. Validate and apply only the selected candidate IDs through scrape_jobs_import.
  5. Write individual email copy through mail_drafts_batch_upsert with stable integration external IDs. Read the saved draft back for its final content and human review URL.
  6. On a later externally scheduled run, read outbound delivery and incoming messages before deciding whether to prepare a reply or follow-up draft.

Keep the integration key in the sandbox's secret configuration. Existing campaign records remain historical; their jobs and drafts cannot resume or send. Prepare new standalone drafts for human review. Scoutello's ordinary CRM workflows remain available for other uses.

Every contact created or reused for a sales project must explicitly reference that project using projectScoutelloId or projectExternalId in contacts_batch_upsert. Mentioning a project in notes or an external ID is not a membership. Contact writes with project references also require projects.write. Read the contact back with contacts.read and projects.read and verify projectParticipations; preserve existing memberships and groups. Generic contacts outside a project do not require a project reference.

Keep companies and verified people as separate contacts. Link a person to the company with companyScoutelloId or companyExternalId, not only companyName. Contact, company relationship, and membership changes are atomic per batch item; invalid references leave no partial contact. Do not invent people or apply provenance tags.

Prepare outgoing emails with mail_drafts_batch_upsert, never as protocol bodies. Grant the new mail-drafts.read and mail-drafts.write scopes explicitly; preparation also requires contacts.read and projects.write. Existing credentials receive no new permissions automatically. Use a stable external ID, expectedVersion: 0 for creation, explicit project/contact references, an accepted approver's User ID, and a configured organization or personal sender scope. Never guess a recipient address or sender configuration.

Keep research in content.notes; only content.subject and content.body are outgoing copy. Draft creation ensures the contact is a project participant. Updates must use the version returned by the latest read; reviewed or dispatched drafts reject edits. Identical retries return the original draft without creating another review. Read back its reviewUrl, draftVersion, contentHash, approval/dispatch status, and eventual mailScoutelloId.

Only the assigned human can approve and send through the existing review screen. Integrations cannot approve, dispatch, or send, even with draft-write access. Preserve original protocols when converting old drafts and cross-reference the replacements. Queue or ambiguous delivery failures require investigation, never a blind resend.

Social post preparation​

Grant social-channels.read, social-posts.read, social-post-drafts.read, and social-post-drafts.write as needed. members_list (members.read) can discover reviewer user IDs. Social tools are advertised only when their scope is granted:

ScopeTools
social-channels.readsocial_channels_list
social-posts.readsocial_posts_list, social_posts_get
social-post-drafts.readsocial_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id
social-post-drafts.writesocial_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload

Read channel capabilities and Scoutello-created history, upload assets, then submit complete channel variants with a named reviewer. Upload tools return HTTP PUT instructions: transfer the original file bytes outside MCP, then finalize the upload with { "assetId": "..." }. Do not embed base64 files in tool arguments.

Use expectedVersion: 0 for new drafts and the current version for pending revisions. mode: "validate" performs no writes. The tool returns the review URL; only a person using the dashboard can approve publishing or scheduling. There is no MCP tool to approve, publish, cancel, or delete a post. Poll draft/history tools for approval, rejection reasons, and per-channel delivery results. Reviewed drafts require a new external ID for further proposals.

See social posts for human review for input examples, upload limits, pagination, and late-review behavior.