npm package: @kognyt/salesforce-mcp
Description: Open-source MCP server that makes any AI assistant a Salesforce expert
Author: Kognyt
Latest version: 0.2.0

# @kognyt/salesforce-mcp

Open-source MCP server that makes any AI assistant a Salesforce expert.

Governor limits, platform constraints, documentation search, and release metadata — available to Claude Code, Cursor, VS Code Copilot, and any MCP-compatible client.

> **Beta Notice**: Sutra Pro is currently in beta and free to use. We'd love your feedback at [hello@kognyt.dev](mailto:hello@kognyt.dev).

## What it does

Sutra gives your AI assistant accurate, structured Salesforce platform knowledge. Instead of hallucinating governor limits or outdated API references, your assistant queries real data curated by [Kognyt](https://kognyt.dev).

No Salesforce org connection required. No authentication needed for free tools.

## Installation

### npm / npx (recommended)

```bash
# Run directly without installing
npx -y @kognyt/salesforce-mcp

# Or install globally
npm install -g @kognyt/salesforce-mcp
```

### From source

```bash
git clone https://github.com/Mahakalp/Sutra.git
cd Sutra
npm install
npm run build
node dist/index.js
```

## Quick start

Add the server to your AI tool's MCP configuration:

### Claude Code

```bash
claude mcp add salesforce-mcp -- npx -y @kognyt/salesforce-mcp
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "salesforce-mcp": {
      "command": "npx",
      "args": ["-y", "@kognyt/salesforce-mcp"]
    }
  }
}
```

### VS Code / Copilot

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "salesforce-mcp": {
      "command": "npx",
      "args": ["-y", "@kognyt/salesforce-mcp"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "salesforce-mcp": {
      "command": "npx",
      "args": ["-y", "@kognyt/salesforce-mcp"]
    }
  }
}
```

## Available tools

Sutra offers two tiers:

### Free Tier (no API key required)

These tools are free and require no authentication:

| Tool | Description |
|------|-------------|
| `mahakalp_sf_constraints` | Governor limits, platform rules, and best practices with values, workarounds, and code examples |
| `mahakalp_sf_doc_search` | Semantic search over official Salesforce documentation |
| `mahakalp_sf_releases` | Release metadata including API versions, status, and dates |

### Pro Tier (Beta - Free during beta)

Pro tools require an API key (free during beta):

| Tool | Description |
|------|-------------|
| `mahakalp_sf_rules` | Best practice rules and coding standards with severity and code examples |
| `mahakalp_sf_patterns` | Reusable code patterns and implementation templates |
| `mahakalp_sf_decision_guides` | Architectural decision guides and trade-off analysis |

To enable Pro tools, set the `MAHAKALP_API_KEY` environment variable. See the [Setup Guide](./docs/setup.md) for details.

### Example usage

Once configured, your AI assistant can answer questions like:

- "What are the SOQL governor limits in Apex triggers?"
- "Search the Salesforce docs for bulk API best practices"
- "What API version does the Spring '26 release use?"

## Roadmap

Coming in future releases:

| Tool | Description |
|------|-------------|
| Apex Class Library | Full method signatures, parameters, return types, and governor limit implications |
| Standard Object Schema | Standard fields, relationships, and FLS patterns |
| LWC Component Reference | Attributes, events, wire adapters, and Apex integration patterns |
| Tribal Knowledge | Community-sourced patterns, anti-patterns, and hard-won lessons |


## How it works

Sutra runs locally on your machine as an MCP server over stdio. When your AI assistant calls a tool, Sutra sends a request to the Kognyt API, which returns curated Salesforce platform knowledge. No code, schema, or org data ever leaves your machine — Sutra only fetches public platform knowledge.

```
Your AI assistant <--stdio--> Sutra (local) <--HTTPS--> Kognyt API
```

## Reliability & Degraded Mode

Sutra is designed to remain functional even when external services are temporarily unavailable:

- **Free tier**: Always works — no external dependencies for entitlement
- **Pro tier**: If the entitlement service is unavailable, Sutra defaults to free tier automatically

When entitlement sync fails:
1. Server logs a warning message
2. Falls back to free tier tools
3. Retries entitlement refresh periodically

This ensures the server continues working even during service disruptions. See [degraded-mode.md](./docs/degraded-mode.md) for detailed behavior.

## Beta Behavior

For the definitive source of truth on free vs Pro tier behavior, entitlements, and open-source boundaries, see [beta-behavior.md](./docs/beta-behavior.md).

This document covers:
- Free vs Pro tool availability
- Entitlement checks and statuses
- Open source vs proprietary boundaries
- Degraded mode behavior
- Offline capabilities

## Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

```bash
git clone https://github.com/Mahakalp/Sutra.git
cd Sutra
npm install
npm run dev    # Run with hot reload
npm run build  # Build for production
```

## License

[MIT](LICENSE)