How to Fix Agentforce 1 MCP Server Startup Failures

Agentforce MCP startup failures usually come from one of six places: local Agentforce Vibes setup, Salesforce registration, transport or authentication, server and network health, tool synchronization, or timeouts. Classify the failure first, then check the matching layer.

The fastest order is:

1. Confirm the local Salesforce DX project and Agentforce Vibes prerequisites.
2. Confirm that the server is registered in the correct Salesforce location.
3. Verify Streamable HTTP, the endpoint URL, and supported OAuth credentials.
4. Call the MCP server directly to prove connectivity and tool responses.
5. Inspect tool synchronization and recreate stale actions.
6. Measure each operation against Agentforce’s 60-second and 120-second timeout budgets.

1. Classify the startup failure

Symptom	Most likely layer	First check
Agentforce Vibes will not start or connect locally	Workspace, extension, org, CLI, Node.js, or proxy	Verify sfdx-project.json, extension status, org connection, and CLI checks
Agentforce cannot find the MCP server	Registration or network	Check the registration location, URL, server process, and network route
Registration appears connected but tools are missing	Tool discovery or definition drift	Inspect trace events and refresh stale actions
Authentication errors	Credential or OAuth mode	Check expiry and use OAuth 2.0 client credentials if authentication is required
Requests hang and then fail	Server latency or aggregate timeout	Measure the slow tool and review Plan Tracer and logs

2. Fix local Agentforce Vibes startup

Check the Salesforce DX workspace

Agentforce Vibes expects a Salesforce DX project. Confirm that the workspace contains sfdx-project.json at the project root. Open the project folder itself rather than a parent directory or an unrelated source folder.

ls -la
cat sfdx-project.json

If the file is absent, open a valid DX project or create the project structure required by your Salesforce workflow before attempting MCP startup again.

Verify the extension and org connection

1. Confirm the Agentforce Vibes extension is installed and active.
2. Confirm the selected Salesforce org is connected and not expired.
3. Run the Salesforce CLI checks used by your project and fix any CLI or Node.js errors before debugging MCP.

A broken org session or inactive extension can look like an MCP server failure because the local client never reaches the server.

Account for a corporate proxy

If outbound traffic must pass through a corporate proxy, configure the proxy through Salesforce CLI. A browser may have internet access while the CLI and extension remain unable to reach the MCP endpoint.

Turn on diagnostics

Enable debug logging and inspect the Agentforce Vibes activity log. Look for the first connection error, the resolved endpoint, the selected org, and the transport being attempted. Later errors are often consequences of the first failure.

3. Register the server in the correct Salesforce location

The registration path depends on who hosts the server.

Server source	Registration path	Additional requirement
External or third-party MCP server	Agentforce Registry	Register the endpoint and allow the required tools
MuleSoft-hosted server	API Catalog	Create and activate the server, then register or allowlist its tools
Salesforce-hosted server	API Catalog	Create and activate the server, then register or allowlist its tools

If a third-party server is entered only in API Catalog, or a MuleSoft server is treated as an external Registry entry, Agentforce may never discover it correctly. Recheck the registered URL after any deployment or hostname change.

4. Verify transport and authentication

Use Streamable HTTP

Agentforce MCP supports the Streamable HTTP transport. A server that exposes only an unsupported transport cannot complete startup, even when the process is healthy.

Confirm that the registered endpoint accepts the MCP requests over Streamable HTTP and that a reverse proxy is not downgrading, buffering, or blocking the required connection.

Use a supported authentication mode

Authentication	Agentforce MCP status
None	Supported
OAuth 2.0 client credentials	Supported
Authorization code	Unsupported
CIMD	Unsupported
DCR	Unsupported
JWT bearer	Unsupported
PKCE	Unsupported
User-level authentication	Unsupported

For OAuth client credentials, verify the client ID, client secret, token URL, scopes, and secret expiry. Re-enter credentials after rotation and check that the named credential points to the current endpoint.

5. Prove endpoint and server health without an LLM

Before involving an agent model, call the MCP server directly. Postman can send the MCP request and return raw JSON, separating authentication, connectivity, and tool-response problems from model behavior.

1. Send the request to the exact URL stored in the Salesforce registration.
2. Use the same authentication configuration as the named credential.
3. Confirm that the response is valid MCP JSON and that the expected tool is advertised.
4. Invoke a small, deterministic tool and record its response time.

For a “server not found” or no-response error, check the network connection, confirm that the server process is running, verify DNS and firewall rules, and make sure the registered URL has not changed. Also confirm that the advertised tool still exists.

6. Resolve tool synchronization and definition drift

Salesforce scans server and tool definitions at runtime. A registration can remain connected while its tool definitions change. When that happens, associated actions may be removed from agent logic.

1. Open trace data and check whether the tool definition is in sync.
2. Compare the currently advertised name, input schema, and description with the action configured in Agentforce.
3. After a server change, remove stale actions and recreate them from the current tool definition.
4. Run the direct Postman call again, then test the action through the agent.

Use the named-credential header x-sfdc-mcp-feature-no-tool-validation: true only as a temporary diagnostic bypass. If the connection works with validation disabled, tool validation or definition drift is the likely cause. Remove the header before activation.

7. Fix timeout failures

Agentforce documents a 60-second limit for an individual registered MCP tool and a 120-second aggregate limit when multiple servers are called. A tool that works locally can still fail in Agentforce if it exceeds either budget.

Limit	Meaning	What to change
60 seconds	Maximum response time cited for one registered tool	Reduce remote calls, paginate work, return a job ID, or move long work outside the synchronous tool call
120 seconds	Aggregate budget when multiple servers are called	Reduce the number of sequential calls and avoid unnecessary tool fan-out

Use Plan Tracer, trace logs, enhanced event logs, and Agent Analytics to identify whether the delay is token acquisition, DNS, the MCP server, a downstream API, or tool execution. Record timings for each dependency instead of treating the whole request as one opaque operation.

8. A repeatable recovery procedure

1. Restart the local extension and reopen the DX project root.
2. Refresh the Salesforce org connection and confirm CLI and Node.js checks pass.
3. Verify proxy settings if the network requires one.
4. Confirm the server is in Agentforce Registry or API Catalog according to its source.
5. Replace the endpoint with the server’s current URL if it changed.
6. Confirm Streamable HTTP and a supported authentication mode.
7. Call the endpoint directly and invoke one simple tool.
8. Inspect trace events for tool synchronization.
9. Recreate stale actions after server or schema changes.
10. Measure response time against 60-second and 120-second budgets.
11. Remove any temporary validation-bypass header and activate the configuration.

9. Common errors and fixes

Error or symptom	Cause	Fix
“Server not found”	Wrong registration path, changed URL, DNS, firewall, or stopped process	Check Registry versus API Catalog, compare the URL, verify the process and network route
No tools appear	Tool not allowlisted, runtime scan failed, or definition drift	Allow the tool, inspect traces, and recreate the action from the current definition
401 or 403 response	Expired or incorrect credentials, unsupported OAuth flow, or missing scope	Use none or OAuth 2.0 client credentials and rotate or correct the named credential
Connection works only with validation disabled	Tool validation or schema mismatch	Compare the advertised schema and remove the temporary bypass after fixing it
Request times out at about one minute	Single tool exceeds the 60-second budget	Optimize the tool, split the work, or make the operation asynchronous
Several tools fail together	Aggregate calls exceed 120 seconds or share a failing dependency	Reduce fan-out and inspect per-server timings in traces and Analytics
Local Vibes never connects	Invalid DX workspace, inactive extension, expired org, CLI/Node.js issue, or proxy	Check each local prerequisite and read the activity log for the first error

10. Reliability, performance, and operating notes

• Keep schemas stable: treat tool names and input schemas as dependencies. Coordinate server changes with action refreshes.
• Prefer small tools: return only the data the agent needs and avoid serial calls to slow downstream services.
• Make retries safe: design write operations to tolerate a repeated request when a client retries after a network interruption.
• Measure outside the model: direct Postman calls and trace timings show whether the fault is transport, authentication, or tool execution.
• Stage changes: validate a new endpoint or schema with one deterministic tool before enabling a larger set of actions.

11. Or skip the browser setup

If your goal is reliable website screenshots for an agent workflow, ScreenshotNeo provides a single HTTP endpoint instead of maintaining a browser capture service. It removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and each response reports its verdict and billing status in headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Plans include 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

12. FAQ

Can Agentforce MCP use authorization-code OAuth?

No. Agentforce MCP supports no authentication or OAuth 2.0 client credentials. Authorization-code and the other user-oriented flows listed above are unsupported.

Where do I register a third-party server?

Use Agentforce Registry for external or third-party servers. MuleSoft and Salesforce-hosted servers use API Catalog.

Why did an action disappear after the server stayed connected?

Salesforce can detect changed tool definitions at runtime and remove associated actions from agent logic. Inspect traces and recreate stale actions.

What should I test before asking the model to call a tool?

Use Postman or another direct HTTP client to verify authentication, connectivity, the advertised tool, and the raw JSON response.

What is the maximum practical response time?

Keep an individual tool under 60 seconds and combined calls under 120 seconds to stay within the cited MCP timeout budgets.