sf-mcp-proxy (Python)

Disclaimer. Independent, unofficial project — not affiliated with, endorsed by, or sponsored by Salesforce, Inc. "Salesforce" and related marks are trademarks of Salesforce, Inc.

Salesforce's Hosted MCP servers (sobject-reads, sobject-all, flows, invocable-actions, …) sit behind OAuth 2.0, and Salesforce does not support Dynamic Client Registration — so every client must be pre-wired with a Consumer Key from a Salesforce External Client App and run the full Authorization Code + PKCE browser flow before it can call a single tool.

sf-mcp-proxy does that once and then gives you:

1. an importable library — an authenticated, in-process mcp.ClientSession that LangChain, LangGraph, and Google ADK can build agents on with no subprocess and no second OAuth layer;

2. a CLI to log in, inspect, and call tools;

3. a proxy (sf-mcp-proxy proxy) that re-exposes one Salesforce MCP server as a plain MCP server (stdio or Streamable HTTP), optionally behind its own OAuth;

4. a chat loop — an LLM in a tool-use loop over one server's tools.

This is a Python port of the TypeScript sf-mcp-proxy. The token cache directory, cache-file naming, StoredSession JSON shape, and encryption-at-rest envelope are byte-compatible with the TS CLI, so the two share ~/.sf-mcp-proxy/.

The OAuth machinery (RFC 9728 discovery, PKCE, the resource indicator, token exchange/refresh) is handled by the official mcp SDK; this package supplies a Salesforce-specific OAuthClientProvider.

API scope. Salesforce owns the Hosted MCP API and can change it without notice; behaviour may drift on later releases and support is best-effort.

Install

pip install sf-mcp-proxy                 # library + CLI + proxy
pip install "sf-mcp-proxy[langchain]"    # + LangChain / LangGraph adapters
pip install "sf-mcp-proxy[adk]"          # + Google ADK toolset
pip install "sf-mcp-proxy[chat]"         # + `sf-mcp-proxy chat`
pip install "sf-mcp-proxy[all]"

Python 3.10–3.13.

Related MCP server: SFCC MCP Server

1. Create a Salesforce External Client App (ECA)

Do this once, in the org you want to connect to.

1. Setup → External Client App Manager → New External Client App.

2. Basic Information — name it, set a contact email, Distribution State Local.

3. API (Enable OAuth Settings) → Enable OAuth:

   • Callback URL: http://localhost:8000/callback (must exactly match OAUTH_REDIRECT_URI).

   • OAuth Scopes: Access MCP servers (mcp_api) and Perform requests at any time (refresh_token).

   • Check Require PKCE.

   • Uncheck Require secret for Web Server Flow / Refresh Token Flow to run as a public client (PKCE only). If you leave them checked, set SF_CONSUMER_SECRET.

4. Policies → OAuth Policies: set Permitted Users, and Issue JWT-based access tokens for named users (so whoami can decode claims).

5. Settings → OAuth Settings → Consumer Key — copy it.

6. Wait ~30 min for the ECA to propagate before first use.

2. Configure

Everything can be passed to the library explicitly, or read from the environment / a .env file in the working directory.

servers.json (searched in the working directory, then ~/.sf-mcp-proxy/servers.json). The reliable way is to copy the exact URL from Salesforce Setup → MCP servers into url:

{
  "servers": [
    { "name": "sobject-reads", "url": "https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads" },
    { "name": "flows", "env": "platform" }
  ]
}

If url is omitted the URL is built as https://api.salesforce.com/platform/mcp/v1/{group}/{name} (production) or …/mcp/v1/sandbox/{group}/{name} (sandbox); group defaults to platform. When absent entirely, a built-in default list is used (sobject-reads, sobject-all, flows, …). -s/--server also accepts a full URL directly.

3. CLI

sf-mcp-proxy login -s sobject-reads -e sandbox   # browser OAuth, caches tokens
sf-mcp-proxy tools -s sobject-reads
sf-mcp-proxy call query -s sobject-reads -a '{"soql":"SELECT Id, Name FROM Account LIMIT 3"}'

-s/--server may be omitted if exactly one server is configured. -e/--env overrides the tier for that run.

4. Library

import asyncio
from sf_mcp_proxy import SalesforceMCP


async def main():
    # One-time interactive login (opens a browser, caches tokens).
    await SalesforceMCP.login("sobject-reads", env="sandbox")

    # Authenticated session. Uses the cached token, auto-refreshes, and by
    # default does NOT open a browser (interactive=False).
    async with SalesforceMCP.connect("sobject-reads", env="sandbox") as sf:
        tools = await sf.list_tools()  # list[mcp.types.Tool]
        result = await sf.call_tool("query", {"soql": "SELECT Id FROM Account LIMIT 1"})
        session = sf.session  # raw mcp.ClientSession


asyncio.run(main())

connect() accepts the same server spec as the CLI (name | bare name | full URL), plus env=, group=, and explicit consumer_key= / consumer_secret= / settings= / passphrase= overrides so a library caller never needs a .env file. list_tools / call_tool transparently reconnect once on an authorization failure (a port of the TS withReauth). SalesforceMCP.connect_sync(...) is a blocking facade for notebooks and the CLI.

5. Framework integrations

LangChain / LangGraph (sf-mcp-proxy[langchain])

from sf_mcp_proxy.integrations.langchain import SalesforceToolkit

async with SalesforceToolkit("sobject-reads", env="sandbox") as tools:
    # `tools` is list[langchain_core.tools.BaseTool] — pass to any agent
    ...

from sf_mcp_proxy.integrations.langgraph import create_salesforce_agent

agent = await create_salesforce_agent(
    model="anthropic:claude-opus-5",
    server="sobject-reads",
    env="sandbox",
)
async for step in agent.astream({"messages": [("user", "how many open opps?")]}):
    ...
await agent.aclose()

load_salesforce_tools(sf) wraps a live session you already own. Tier B — salesforce_stdio_connection(...) — returns a langchain-mcp-adapters connection pointed at a spawned sf-mcp-proxy proxy.

Google ADK (sf-mcp-proxy[adk])

from google.adk.agents import LlmAgent
from sf_mcp_proxy.integrations.adk import SalesforceToolset

toolset = SalesforceToolset(server="sobject-reads", env="sandbox")
agent = LlmAgent(model="gemini-2.5-pro", name="sf", tools=[toolset])
...
await toolset.close()

Tier B — salesforce_stdio_connection_params(...) returns StdioConnectionParams for ADK's own McpToolset.

Runnable examples are in examples/.

6. Proxy mode

sf-mcp-proxy proxy re-exposes one Salesforce MCP server as a plain MCP server. The proxy owns the Salesforce OAuth (the token cached by login), so downstream clients need no Salesforce auth of their own. Every request runs as the Salesforce user who authorized the proxy (one identity per proxy process).

stdio — for clients that spawn a subprocess:

{
  "mcpServers": {
    "salesforce-sobject-reads": {
      "command": "sf-mcp-proxy",
      "args": ["proxy", "-s", "sobject-reads", "-e", "sandbox", "--no-login"]
    }
  }
}

Streamable HTTP — for clients that take a URL:

sf-mcp-proxy proxy -s sobject-reads -e sandbox --no-login \
  --http --port 9000 --auth-token "$(openssl rand -hex 16)"
# → endpoint: http://127.0.0.1:9000/mcp   (send: Authorization: Bearer <token>)

--host/--port/--public-url/--auth-token fall back to $HOST/$PORT/$PUBLIC_URL/$SF_PROXY_AUTH_TOKEN. For a remote client, bind --host 0.0.0.0 and put a TLS reverse proxy in front (the proxy speaks plain HTTP), and always set --auth-token or --oauth.

--oauth

Runs a minimal, spec-shaped OAuth 2.0 Authorization Server + Resource Server on the same port: RFC 9728 / RFC 8414 discovery, RFC 7591 Dynamic Client Registration (POST /register), Authorization Code + PKCE (S256), and an Approve/Deny page on every /authorize request. A spec-compliant client discovers everything from the 401 it gets hitting /mcp. Manage clients with sf-mcp-proxy oauth-clients -s … [--revoke <id>]. Behind a reverse proxy, pass --public-url https://your.host so the discovery documents advertise the right address. This layer only gates who reaches the proxy — every approved client still acts as the one identity that ran login.

Docker

A Dockerfile runs proxy --http --no-login and reads $HOST, $PORT, $PUBLIC_URL, $SF_PROXY_AUTH_TOKEN from the environment.

docker build -t sf-mcp-proxy .
docker run --rm -p 8080:8080 \
  -e SF_CONSUMER_KEY=... -e SF_PROXY_AUTH_TOKEN=... -e SF_TOKEN_PASSPHRASE=... \
  -v ~/.sf-mcp-proxy:/home/app/.sf-mcp-proxy \
  sf-mcp-proxy -s sobject-reads -e sandbox

There's no browser in the container, so --no-login is on: run sf-mcp-proxy login once on your machine and make the token cache available to the container. On a stateless host (Cloud Run, etc.) mount a persistent volume at /home/app/.sf-mcp-proxy (the Salesforce refresh token rotates and is written back), set SF_TOKEN_PASSPHRASE from a secret, and pin --max-instances 1 --min-instances 1 (a Streamable HTTP session is held in memory by the instance that created it).

7. Chat mode (sf-mcp-proxy[chat])

sf-mcp-proxy chat -s sobject-reads
you> how many open opportunities are closing this quarter?
⚙  soqlQuery({"soql":"SELECT COUNT() FROM Opportunity WHERE IsClosed = false AND ..."})
   run soqlQuery? [y/N] y

Tool calls whose name looks like a write (create/update/delete/run/…) prompt for confirmation. -y approves everything; --confirm-all prompts for every call. In-chat commands: /tools, /reset, /quit.

SFCHAT_API_KEY works as the key for any provider; SFCHAT_MODEL / SFCHAT_BASE_URL persist per-run overrides. The model must support tool calling.

How auth works

1. First request to the MCP server returns 401. The SDK discovers https://api.salesforce.com/.well-known/oauth-protected-resource/…, which names the org's authorization server.

2. It builds the authorize URL with PKCE (S256), the mcp_api refresh_token scopes, and resource=<server URL> (RFC 8707), then opens the browser.

3. Salesforce redirects to http://localhost:<port>/callback with a code; a one-shot loopback server catches it and the SDK exchanges it for tokens.

4. Tokens are written to ~/.sf-mcp-proxy/<sha256(url)[:32]>.json (dir 0700, files 0600; encrypted if SF_TOKEN_PASSPHRASE is set). Later runs reuse and silently refresh the access token.

SF_AUTH_SERVER_URL (a My Domain host) bypasses discovery and uses {base}/services/oauth2/{authorize,token,revoke} directly.

Troubleshooting

Development

uv sync --all-extras --group dev
uv run pytest -q
uv run ruff check . && uv run ruff format --check .
uv run mypy sf_mcp_proxy

License

MIT © Ocky Harliansyah — see LICENSE.