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:

Open Claude Desktop
Go to View → Developer → Show Logs

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:

List all your connected databases
Fetch schemas for validation
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:

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

The new version simplifies configuration to just one environment variable!

License

MIT

relentless-mcp

Relentless MCP Server v2.0

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:

Open Claude Desktop
Go to View → Developer → Show Logs

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:

List all your connected databases
Fetch schemas for validation
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:

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

The new version simplifies configuration to just one environment variable!

License

MIT