MCP Integration Server (Salesforce • Atlassian • Supabase)

A TypeScript Model Context Protocol (MCP) server that exposes your Salesforce, Atlassian (Jira/Confluence), and internal resources as tools and resources agents can call in a standardized way.

This README covers:

What the server does How to configure credentials How to build and run locally How to smoke-test tools without any desktop client Operational/safety notes

At a glance

Language/Runtime: TypeScript on Node 18+ (Node 20+ recommended) MCP Transport: stdio (the MCP server is launched by the client and communicates over standard I/O) Key integrations: Salesforce REST, Jira/Confluence REST, Supabase (logging + example resources) Hardening included: central HTTP client with timeouts, basic log redaction, environment isolation

Repo layout

Repo layout

Prerequisites Node.js 18+ (20+ recommended) An editor with TypeScript support (Optional) Accounts/API tokens for Salesforce, Jira, Confluence, Supabase

Environment variables Copy .env.example to .env in the project root and fill in what you need. Only the integrations you use must be set.

Supabase (used for logging + example resources) Variable Description SUPABASE_URL Your Supabase project URL SUPABASE_ANON_KEY or SUPABASE_SERVICE_ROLE_KEY Key to access your Supabase (start with ANON; use Service Role only with proper RLS)

Backward-compatible names VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY are still read by runtime/context.ts, but prefer the SUPABASE_* names for clarity.

Salesforce

Install, build, and run locally

From the project root: Install deps npm install

Build the MCP server npm run build:mcp

This compiles TypeScript to mcp-server/dist/index.js.

Smoke-test a tool (no desktop client required) The smoketest script launches the MCP server over stdio and calls a tool by name.

Show available tools (optional): node scripts/list-tools.mjs

Call a safe tool first (from utilities.ts), e.g.:

mac/linux

node scripts/mcp-smoketest.mjs calculate '{"expression":"2+2*5"}'

windows powershell (escape quotes)

node scripts/mcp-smoketest.mjs calculate "{""expression"":""2+2*5""}"

Call an integration tool (only after your .env is set), for example:

Salesforce (read-only)

node scripts/mcp-smoketest.mjs salesforce_query '{"query":"SELECT Id, Name FROM Account LIMIT 1"}'

Jira (search)

node scripts/mcp-smoketest.mjs jira_search_issues '{"jql":"assignee = currentUser() ORDER BY created DESC"}'

What you should see: JSON output with a content array containing the tool’s result (in text-serialized JSON). If an auth error appears, recheck your .env.

How it works (short version)

mcp-server/index.ts stands up a JSON-RPC MCP Server over stdio with handlers for:

ListTools → discovers all tools (from tools/)

CallTool → routes tool calls to the correct handler

ListResources/ReadResource → exposes read-only document/analytics/salesforce/atlassian resources

mcp-server/runtime/context.ts centralizes:

Environment variable parsing

Supabase client creation

mcp-server/runtime/http.ts provides a shared axios instance with:

20s timeout

Controlled status handling

Tools log to Supabase’s api_logs (if configured). Arguments are passed through a small redaction helper to avoid storing secrets.

Configuration details

HTTP client: mcp-server/runtime/http.ts sets a 20s timeout and friendly status handling (validateStatus). If you need retries, add an axios interceptor there once.

Logging: Tool handlers call a logApiCall helper that inserts rows into api_logs. Sensitive fields like tokens are redacted before insert.

Responses: Tools consistently return { content: [{ type: "text", text: "" }] }. This keeps client parsing predictable across runtimes.

Safety notes

Start read-only. Begin with tools like salesforce_query or jira_search_issues. Enable writes (create/update/delete/transition) later.

Guard writes. A simple pattern is to require a confirm: "yes" or a dryRun: true default and only execute state-changing calls when explicitly requested. (Planned: dryRun fields on Salesforce/Atlassian write tools.)

Least privilege. Use the minimum API scopes necessary for each integration.

RLS on Supabase. If you use ANON keys, set Row Level Security so logs are not world-readable.

Troubleshooting

Cannot find module mcp-server/dist/index.js You skipped the build step or ran from the wrong folder. Fix: npm run build:mcp then ensure mcp-server/dist/index.js exists.

Hangs or very slow responses External API may be slow. Timeouts are set to 20s; adjust in runtime/http.ts if needed.

Auth errors Double-check your .env. Try a non-integrated tool (calculate) to confirm the server/client plumbing.

Tool not found Run node scripts/list-tools.mjs to see the exact tool names, then pass one to the smoketest.

Extending

Add new integrations by creating a new file in mcp-server/tools/yourservice.ts and registering tools that return structured results.

Expose read-only views through mcp-server/resources/yourservice.ts with your own URI scheme (e.g., yourservice://…).

If you later use a GUI agent runtime or desktop client, point it at node mcp-server/dist/index.js as an MCP stdio server.

Scripts reference

package.json (root) includes:

build:mcp – compile the MCP server

mcp:server – run the compiled server directly (usually launched by a client)

(optional) tools – list tool names

(optional) smoke – shorthand to run the smoketestMCPtest