npm package: @orchestraprime/mcp-server
Description: OrchestraPrime MCP server — CTWise regulatory intelligence and SanctionsWise screening for Claude
Author: OrchestraPrime LLC
Latest version: 2.0.1

# @orchestraprime/mcp-server

**Regulatory intelligence and sanctions screening for Claude.**

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives Claude direct access to OrchestraPrime APIs:

- **CTWise** -- Authoritative regulatory intelligence (FDA, ICH, EMA, WHO, CDISC)
- **SanctionsWise** -- Global sanctions screening (OFAC, EU, UK, UN, BIS)

---

## Quick Start

### 1. Install

```bash
npm install -g @orchestraprime/mcp-server
```

Or run directly with npx:

```bash
npx @orchestraprime/mcp-server
```

### 2. Get API Keys

1. Visit [app.orchestraprime.ai](https://app.orchestraprime.ai)
2. Create an account or sign in
3. Navigate to **API Keys**
4. Generate keys for the products you need:
   - **CTWise** key (starts with `ctw_`)
   - **SanctionsWise** key (starts with `sw_`)

### 3. Configure Claude Desktop

Add to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "orchestraprime": {
      "command": "npx",
      "args": ["@orchestraprime/mcp-server"],
      "env": {
        "CTWISE_API_KEY": "ctw_your_key_here",
        "SANCTIONSWISE_API_KEY": "sw_your_key_here"
      }
    }
  }
}
```

### 4. Restart Claude Desktop

After saving the config, restart Claude Desktop. You should see the OrchestraPrime tools available in conversations.

---

## Available Tools

### CTWise -- Regulatory Intelligence

| Tool | Description | Example Prompt |
|------|-------------|----------------|
| `search_regulations` | Semantic search across FDA, ICH, EMA, WHO, CDISC | "What FDA requirements apply to AI diagnostic software?" |
| `get_rule_details` | Full rule text and citations | "Show me the details of FDA-2024-D-1234" |
| `list_sources` | Available regulatory data sources | "What regulatory databases are available?" |
| `check_cds_classification` | FDA CDS 4-criteria exemption analysis | "Does my clinical decision support tool need FDA clearance?" |
| `check_protocol_compliance` | ICH GCP E6(R2) protocol analysis | "Check this clinical trial protocol for compliance gaps" |
| `get_recent_updates` | Latest regulatory guidance changes | "What FDA guidance changed in the last 30 days?" |

### SanctionsWise -- Sanctions Screening

| Tool | Description | Example Prompt |
|------|-------------|----------------|
| `screen_entity` | Screen individual/organization against sanctions | "Screen Viktor Bout against OFAC and EU sanctions lists" |
| `screen_batch` | Screen multiple entities at once (up to 100) | "Screen these 5 companies for sanctions matches" |
| `list_sanctions_lists` | Available sanctions lists and coverage | "What sanctions lists are available?" |

### Resources

| Resource | URI | Description |
|----------|-----|-------------|
| CTWise Help | `ctwise://help` | Usage guide for regulatory tools |
| CTWise Sources | `ctwise://sources` | Available regulatory databases |
| SanctionsWise Help | `sanctionswise://help` | Usage guide for screening tools |
| SanctionsWise Lists | `sanctionswise://lists` | Available sanctions lists |

---

## Usage Examples

### Regulatory Search

> "What FDA requirements apply to software that uses AI for radiology diagnosis?"

Claude will use `search_regulations` to query CTWise and return authoritative, citable regulatory guidance.

### CDS Classification

> "I'm building a clinical decision support tool that displays lab results for physicians. Does it need FDA clearance?"

Claude will use `check_cds_classification` to analyze your software against the FDA CDS 4-criteria from the 21st Century Cures Act.

### Sanctions Screening

> "Screen Acme International Corp against all available sanctions lists"

Claude will use `screen_entity` to check the entity against OFAC, EU, UK, UN, and BIS sanctions lists in real time.

### Protocol Compliance

> "Review this clinical trial protocol for ICH GCP compliance: [paste protocol text]"

Claude will use `check_protocol_compliance` to identify gaps against ICH GCP E6(R2) requirements.

---

## Security

### API Key Handling

- API keys are stored **locally** in your Claude Desktop config
- Keys are **never** sent to Claude or Anthropic -- they stay on your machine
- Keys are validated at startup against expected patterns (`ctw_*` / `sw_*`)
- Keys are **never logged** -- the server sanitizes all log output

### Sanctions Screening Compliance

- `screen_entity` and `screen_batch` results are **never cached**
- Every screening call hits the live API with current sanctions data
- Each screening returns a unique `screening_id` for audit trail
- Results should be reviewed by compliance professionals as part of a comprehensive compliance program

### Data Flow

```
Claude Desktop  --stdio-->  MCP Server (local)  --HTTPS-->  OrchestraPrime APIs (AWS)
                            Your machine                     api.ctwise.ai
                            API keys stay here               api.sanctionswise.orchestraprime.ai
```

### Best Practices

1. **Rotate keys regularly** -- Generate new keys from [app.orchestraprime.ai](https://app.orchestraprime.ai)
2. **Use separate keys** per environment (dev vs production)
3. **Never commit keys** to version control
4. **Set keys via environment variables** -- avoid hardcoding in scripts

---

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CTWISE_API_KEY` | For CTWise tools | Starts with `ctw_` |
| `SANCTIONSWISE_API_KEY` | For SanctionsWise tools | Starts with `sw_` |
| `LOG_LEVEL` | No | `debug`, `info` (default), `warn`, `error` |

You don't need both keys. If you only use CTWise tools, only `CTWISE_API_KEY` is required. The server warns but doesn't fail if a key is missing.

### Running Directly

```bash
# With environment variables
CTWISE_API_KEY=ctw_yourkey SANCTIONSWISE_API_KEY=sw_yourkey npx @orchestraprime/mcp-server

# Or export first
export CTWISE_API_KEY=ctw_yourkey
export SANCTIONSWISE_API_KEY=sw_yourkey
npx @orchestraprime/mcp-server
```

---

## Troubleshooting

### Server Won't Start

**Symptom:** Claude Desktop shows "MCP server failed to connect"

**Fixes:**
1. Verify Node.js >= 18: `node --version`
2. Check your config JSON is valid (no trailing commas)
3. Ensure the `env` block has correct key names
4. Try running manually: `npx @orchestraprime/mcp-server`

### "Invalid API key" Error

**Symptom:** Tools return "Authentication failed"

**Fixes:**
1. Verify key format: CTWise keys start with `ctw_`, SanctionsWise with `sw_`
2. Check for extra whitespace in your config
3. Generate a new key at [app.orchestraprime.ai](https://app.orchestraprime.ai)

### "API key not configured" Warning

**Symptom:** Server starts but warns about missing keys

**Explanation:** This is expected if you only use one product. CTWise tools require `CTWISE_API_KEY`, SanctionsWise tools require `SANCTIONSWISE_API_KEY`.

### Tools Not Appearing in Claude

**Symptom:** No OrchestraPrime tools visible in Claude Desktop

**Fixes:**
1. Fully restart Claude Desktop (not just close/reopen a conversation)
2. Verify config file location is correct for your OS
3. Check Claude Desktop logs for MCP connection errors
4. Test with MCP Inspector: `npx @modelcontextprotocol/inspector npx @orchestraprime/mcp-server`

### Rate Limiting

**Symptom:** "Too many requests" errors

**Explanation:** API rate limits apply per key. The server retries automatically with exponential backoff (up to 3 retries). If you consistently hit limits, upgrade your plan at [app.orchestraprime.ai](https://app.orchestraprime.ai).

### Slow Responses

**Symptom:** Tools take > 2 seconds to respond

**Explanation:**
- First calls are slower (no cache). Subsequent calls for `search_regulations`, `list_sources`, and `get_rule_details` are cached (5min and 1h TTLs)
- `screen_entity` and `screen_batch` are never cached (compliance requirement) and depend on API latency
- Request timeout is 25 seconds; if the API is slow, the server will retry

---

## Architecture

This server is built on the [@orchestraprime/rest-mcp-bridge](https://github.com/orchestraprime/rest-mcp-bridge) framework -- a generic YAML-configuration-driven system that converts REST APIs into MCP servers.

```
@orchestraprime/mcp-server
  |
  +-- config/              YAML tool & resource definitions
  |     +-- server.yaml    Server identity
  |     +-- apis.yaml      API connections (CTWise + SanctionsWise)
  |     +-- tools/         9 tool definitions
  |     +-- resources/     4 resource definitions
  |
  +-- escape-hatches/      TypeScript overrides for complex logic
  |     +-- L1: pre_request       (data injection)
  |     +-- L2: post_response     (response transforms)
  |     +-- L3: custom_formatter  (output formatting)
  |     +-- L4: full handler      (local-only analysis)
  |
  +-- index.ts             4-line entry point
```

### Tool Classification

| Category | Count | Examples |
|----------|-------|---------|
| Pure YAML (no code) | 4 | search_regulations, get_rule_details, list_sources, list_sanctions_lists |
| Hybrid (YAML + escape hatch) | 3 | screen_entity, screen_batch, get_recent_updates |
| Full handler (no API call) | 2 | check_cds_classification, check_protocol_compliance |

---

## Pricing

The MCP server is free and open-source. API usage is billed through your OrchestraPrime subscription:

| Plan | Price | Included |
|------|-------|----------|
| Free Trial | $0 | 100 queries/month |
| Starter | $99/mo | 5,000 queries/month |
| Pro | $299/mo | 25,000 queries/month |
| Enterprise | Custom | Unlimited + SLA |

Sign up at [app.orchestraprime.ai](https://app.orchestraprime.ai).

---

## Support

- **Documentation:** [docs-ctwise.orchestraprime.ai](https://docs-ctwise.orchestraprime.ai) / [docs-sanctionswise.orchestraprime.ai](https://docs-sanctionswise.orchestraprime.ai)
- **Issues:** [github.com/orchestraprime/mcp-server/issues](https://github.com/orchestraprime/mcp-server/issues)
- **Email:** support@orchestraprime.ai

---

## License

MIT -- see [LICENSE](./LICENSE) for details.