Connect a Salesforce agent over MCP

Prerequisites

• A configured Vivly agent source checkout with its Python environment and dashboard running.
• A Salesforce connection created through browser OAuth in the dashboard. Client-credentials connections are not supported here.
• The saved connection ID and state directory. Run the server under the Windows user who owns the saved credentials.
• An MCP client that supports Streamable HTTP and a custom Authorization header.

Start the server

From the agent checkout, replace the uppercase placeholders with your dashboard connection values. The first command prints a token once and its expiry; tokens expire after 24 hours by default.

.\.venv\Scripts\python.exe -m vivly_graph.cli agent-mcp-token --home STATE-DIRECTORY --connection-id SAVED-OAUTH-CONNECTION-ID
.\tools\Start-AgentMcp.ps1 -StateDirectory STATE-DIRECTORY -ConnectionId SAVED-OAUTH-CONNECTION-ID -Port 8043

Keep the token private. This source-checkout process is not a Windows service; arrange restart and monitoring for your deployment.

Connect your client

Transport

Streamable HTTP

Local URL

http://127.0.0.1:8043/mcp

Header

Authorization: Bearer YOUR-MCP-TOKEN

For a remote client, use your administrator-configured HTTPS endpoint. This server uses manually issued bearer tokens, not automatic MCP OAuth discovery. Salesforce sign-in happens in the dashboard first.

Validate a read

Refresh the client tool list and call list_agents. Start a small investigation with ask_agent, then use get_investigation to retrieve its state and results. Compare the answer with records visible to the same Salesforce user.

Try: “List accounts and their case counts, including accounts with zero cases.” Then ask about related emails and compare blockers across cases. The examples below use fictional records and do not contact Salesforce.

From a question to a supported answer.

Follow one conversation from account counts to the evidence behind each case.

vivlySalesforce investigationInteractive example / Fictional records

1. Account counts2. Cases & emails3. Reason across cases

List all accounts and the number of cases each has.

Trace Completed

1. Resolve Account and Case relationships
2. Count cases by account
3. Include accounts with zero cases

5 accounts, 16 associated cases.

All accounts in this example are included, even those without cases.

Account	Case count
Anchor Robotics	0
Atlas Holdings	2
Aurora Textiles	2
Edge Communications	8
Northstar Print Works	4

Investigations and approval

The server revalidates the Salesforce identity on each authenticated request. An investigation is distinct from an approved write. Review the proposed action, target records, and evidence before execution.

Follow-up email sending is an opt-in development capability with native human confirmation for the exact draft revision. A model-supplied approval flag is not consent. If the client cannot collect confirmation, sending does not proceed.

Troubleshooting

To revoke tokens for the signed-in identity, run agent-mcp-revoke with the same --home and --connection-id arguments.