MCP integration
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:
- Select only the read and write scopes the MCP client needs.
- Save the complete
sctl_api_key when it is shown. Scoutello displays it once. - 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 scope | MCP tools |
|---|---|
contacts.read | contacts_list, contacts_get, contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list, tasks_get, tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list, protocols_get, protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list, opportunities_get, opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list, projects_get, projects_get_by_external_id |
projects.write | projects_batch_upsert |
events.read | events_list, events_get, events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list, mails_get |
tags.read | tags_list |
whoami is always available to an authenticated connection. Tool inputs and results follow the same schemas and response envelopes as their linked REST operations.
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
| Result | What to check |
|---|---|
401 authentication error | Confirm that the complete key is present and the header uses Bearer, with no quotes around the key. |
403 authorization error | Grant the required scope by rotating the integration key, then update the client with the replacement key. |
404 at the MCP URL | Confirm the URL ends in /api/v1/mcp. The MCP service may not yet be enabled in that Scoutello environment. |
429 rate-limit error | Wait until the returned reset time before retrying. REST and MCP consume the same integration quota. |
| Tool is missing | Check 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.