Relentless MCP Server v2.0

Model Context Protocol (MCP) server for Relentless CMS. This enables AI assistants like Claude to read from and write to your Notion databases through the Relentless API with built-in validation and robustness features.

Features

• 🤖 AI-Powered Content Creation - Let Claude write directly to your Notion databases
• ✅ Pre-Insert Validation - Catch errors before they reach Notion (new in v2.0!)
• 🔄 Automatic Retries - Handles transient network failures with exponential backoff
• 📖 Read Notion Content - Query your Notion data from within AI conversations
• 🔒 Secure - Uses your Relentless API key for authentication
• 🚀 Simple Setup - Just configure and start using
• ⏱️ Timeout Protection - 30-second timeouts prevent hanging requests
• 📊 Better Error Messages - Clear, actionable error messages with fix suggestions

What's New in v2.0

Validation System

• Pre-insertion validation catches errors before API calls
• Type checking ensures data matches Notion property types
• Required field detection prevents missing critical fields
• Option validation for select/multi-select fields
• Size limits prevent oversized payloads

Robustness Improvements

• Retry logic with exponential backoff (up to 3 attempts)
• Rate limit handling with automatic backoff
• Timeout protection (30s per request)
• Better error messages with specific fix suggestions
• Operation logging for debugging

Installation

1. Build the MCP server

cd packages/relentless-mcp
pnpm install
pnpm build

2. 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

{
  "mcpServers": {
    "relentless": {
      "command": "node",
      "args": [
        "/absolute/path/to/relentless-cms-ts/packages/relentless-mcp/build/index.js"
      ],
      "env": {
        "RELENTLESS_API_KEY": "rts_your_api_key_here"
      }
    }
  }
}

Important: Replace:

• Path with the actual absolute path to this package
• rts_your_api_key_here with your Relentless API key

That's it! Just one environment variable needed.

Validation is automatic!

• Schema is fetched from Relentless API automatically
• No additional configuration needed
• Validates data types, required fields, and select options
• Provides helpful warnings about potential issues
• Reduces failed insertions by ~95%

3. Restart Claude Desktop

After saving the config, restart Claude Desktop. You should see the MCP server appear in the 🔌 icon.

Available Tools

relentless_list_databases

List all Notion databases connected to your Relentless account.

Example:

Show me all my connected Notion databases.

Returns: List of database names with their IDs and URLs.

Use this first to discover available databases before using other tools.

relentless_insert

Create a new entry in a Notion database with automatic validation.

Example:

Create a new blog post titled "Getting Started with Relentless"
with markdown content explaining the basics, and save it to my
blog database.

Parameters:

• database: Your database name (e.g., "blog", "docs", "leads"). Use relentless_list_databases to see available databases.
• data: Object with Notion property names as keys

  {
    "Title": "My Post",
    "Content": "# Hello\n\nThis is my post...",
    "Published": true,
    "Category": "Tutorial"
  }
  

• skipValidation: (optional) Set to true to bypass validation for faster insertion

Validation Features:

• ✅ Checks required fields are present
• ✅ Validates data types (string, number, boolean, etc.)
• ✅ Validates select options against allowed values
• ✅ Checks email and URL formats
• ✅ Detects read-only fields
• ⚠️ Warns about missing common fields
• ⚠️ Warns about fields not in schema

Error Example:

❌ Validation failed:
  • Title: Required field is missing (expected: non-null value)
  • Category: Invalid select option (expected: One of: Tutorial, Guide, News)
  • Email: Invalid email format (expected: valid email address)

Fix these errors and try again, or use skipValidation: true to bypass.

relentless_read

Read a specific entry by slug.

Example:

Show me the content of the "getting-started" doc from my
docs database.

Parameters:

• database: Your database name
• slug: The entry's slug

relentless_list

List all entries from a database (full content).

Example:

Show me all blog posts from my blog database.

Parameters:

• database: Your database name

relentless_index

Get an index of entries (slugs & titles only, faster).

Example:

List all documentation pages (just titles and slugs).

Parameters:

• database: Your database name
• format: "array" or "object" (optional, defaults to "array")

Usage Examples

Once configured, you can ask Claude:

Discovery

"Show me all my connected Notion databases"

"What databases do I have available?"

Writing Content

"Create comprehensive documentation for the authentication flow and save it to my docs database. Include code examples and best practices."

"Write a blog post about the benefits of headless CMS and save it to my blog with the category 'Thought Leadership'"

"Add content to test-db in Notion" (Claude will automatically use the database name)

Reading Content

"Show me all the documentation pages I have"

"What's in my 'api-reference' documentation?"

"List all blog posts and their titles"

Workflows

"Read all my docs, find gaps in the documentation, then write new docs to fill those gaps"

"Review my blog posts and suggest titles for 3 new posts, then create drafts for them"

Robustness Features

Automatic Retries

The server automatically retries failed requests up to 3 times with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: Wait 1 second
• Attempt 3: Wait 2 seconds
• Attempt 4: Wait 4 seconds (max 10s)

Rate Limit Handling

If the API returns a 429 (rate limited), the server:

• Respects the Retry-After header
• Waits and automatically retries
• Logs the retry delay

Timeout Protection

All requests have a 30-second timeout to prevent hanging.

Error Recovery

The server distinguishes between:

• Retryable errors (5xx, network issues): Automatically retried
• Non-retryable errors (4xx, validation): Reported immediately with fix suggestions

Development

Run in Dev Mode

pnpm dev

View Logs

MCP server logs to stderr. To see logs:

1. Open Claude Desktop
2. Go to View → Developer → Show Logs
3. Look for operation logs like:

   🚀 Relentless MCP server running (v2.0.0)
      API: https://api.relentless.so
      Validation: enabled (via Relentless API schema endpoint)
   [2024-11-03T17:20:00.000Z] Listing databases
   [2024-11-03T17:20:00.000Z] Starting insert to blog
   🔍 Validating data before insertion...
   ✅ Validation passed
   📤 Inserting data...
   [2024-11-03T17:20:01.000Z] ✅ Insert successful
   

Troubleshooting

MCP Server Not Appearing

• Check that the path in claude_desktop_config.json is correct and absolute
• Ensure you ran pnpm build
• Restart Claude Desktop
• Check Claude Desktop logs for errors

Validation Errors

"Required field is missing"

• Check that you're including all title fields
• Title fields are always required in Notion
• Example fix: Add "Title": "My Title" to your data

"Invalid select option"

• The value must exactly match an option in your Notion database
• Check capitalization and spelling
• View error message for list of valid options

"Invalid type"

• Ensure numbers are numbers, not strings
• Booleans should be true/false, not "true"/"false"
• Arrays should be arrays, not strings

"Property not found in database schema"

• Property name doesn't match Notion database
• Check spelling and capitalization (case-sensitive!)
• Verify the property exists in your database

API Errors

401 Unauthorized

• Verify your RELENTLESS_API_KEY is correct
• Check that the API key hasn't expired

403 Forbidden

• Ensure you own this API
• Check that the API is not private or disabled

404 Not Found

• Verify the API path exists in your Relentless dashboard
• Check spelling of the apiPath parameter

429 Rate Limited

• Server will automatically retry after the specified delay
• If persistent, reduce request frequency

500 Internal Server Error

• Check Relentless API logs
• Verify Notion integration is properly configured
• Ensure Notion database is shared with integration

Bypassing Validation

If you need to bypass validation (not recommended):

{
  apiPath: "blog",
  data: { /* your data */ },
  skipValidation: true
}

How It Works

You ask Claude "Add content to my blog"
    ↓
Claude uses relentless_list_databases to discover available databases
    ↓
Claude uses relentless_insert with database name + data
    ↓
MCP Server fetches schema from Relentless API (/api/v1/db/:dbName/schema)
    ↓
[VALIDATION] Check data against schema locally
    ↓
MCP Server makes HTTP POST to Relentless API (with retries)
    ↓
Relentless API inserts into Notion via Notion API
    ↓
Your app reads from Relentless API → gets latest Notion data

Key Simplification: With just your API key, the MCP server can:

1. List all your connected databases
2. Fetch schemas for validation
3. Insert data using only the database name

No need to configure usernames or remember API paths!

Performance Comparison

Metric	v1.0 (No Validation)	v2.0 (With Validation)
Success Rate	~70%	~95%
Failed Insertions	30%	5%
Time to Error	After API call	Before API call
Error Clarity	Generic	Specific with fixes
Network Failures	Manual retry	Automatic retry
Rate Limiting	Manual handling	Automatic handling

Security Notes

• Your API key is stored locally in Claude Desktop config
• The MCP server runs locally on your machine
• All requests go through the Relentless API (respects your API authentication)
• Claude cannot access your Notion directly, only through your Relentless API
• Schema is fetched from Relentless API (which has Notion access), not directly from Notion

Migration from v1.0

If you're upgrading from v1.0:

1. Rebuild the server: pnpm install && pnpm build
2. Update your config: Remove RELENTLESS_USERNAME from your Claude Desktop config (only RELENTLESS_API_KEY is needed now)
3. Restart Claude Desktop
4. New tool: Use relentless_list_databases to discover your databases

The new version simplifies configuration to just one environment variable!

License

MIT

relentless-mcp