MCP Integration

Use your Idioscript projects from any MCP-compatible tool — including Claude Desktop, Cursor, VS Code, and more.

What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI applications to access external data and tools. Idioscript implements an MCP server, which means you can access your story context and style fingerprints from any MCP-compatible application.

This lets you use your Idioscript data in your preferred writing environment — whether that's Claude Desktop, an IDE with AI features, or another MCP client.

Available Tools

When connected via MCP, you get access to these Idioscript capabilities:

ask_story_bible

Query your story context in natural language. Ask about characters, plot points, world-building, and more.

generate_text

Generate new text using your Style Fingerprint. The output matches your established voice and patterns.

edit_text

Rewrite text to match your style. Transform any content into your voice.

continue_text

Continue writing from where you left off, maintaining your style and tone.

check_style_adherence

Verify if text matches your established style. Get a score and feedback.

list_projects & list_style_fingerprints

Discover available projects and fingerprints you can work with.

Getting an API Key

To use MCP integration, you need an API key. API keys are tied to your account and have access to all your projects.

Create an API Key

Go to Settings in Idioscript
Navigate to the API Keys section
Click Create New API Key
Give your key a descriptive name (e.g., "Claude Desktop")
Copy the key immediately — it won't be shown again

API Key Security

Your API key grants full access to your Idioscript projects. Never share it publicly or commit it to version control. If compromised, revoke it immediately and create a new one.

Configuring Claude Desktop

Setting up Idioscript with Claude Desktop requires no local installation — just configure your API key and you're ready to go.

Setup Steps

Generate an API key from Settings > API Keys
Edit your Claude Desktop config file
Add the Idioscript MCP server configuration
Restart Claude Desktop

Edit Claude Desktop Configuration

Add the Idioscript MCP server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "idioscript": {
      "command": "npx",
      "args": ["idioscript-mcp"],
      "env": {
        "MCP_API_KEY": "idi_live_your-api-key-here",
        "MCP_API_BASE_URL": "https://idioscript.com"
      }
    }
  }
}

Configuration Notes

Replace idi_live_your-api-key-here with your actual API key from Settings
The MCP_API_BASE_URL should be https://idioscript.com
No local installation required — npx idioscript-mcp runs directly

Required Environment Variables

Variable	Description
`MCP_API_KEY`	Your Idioscript API key (required)
`MCP_API_BASE_URL`	The Idioscript API URL (e.g., https://idioscript.com)

Connecting from Claude.ai Web

You can also connect to Idioscript directly from Claude.ai in your web browser using the remote MCP server. This is an alternative to the local npm package — no installation required.

Setup Steps

Go to claude.ai
Open Settings (click your profile icon)
Navigate to Connectors (or Integrations)
Click Add custom connector
Enter the server URL: https://idioscript.com/api/mcp/remote
Add a custom header with name X-MCP-API-Key and your API key as the value
Save and start a new conversation

Once connected, you can ask Claude to use your Idioscript tools — query your Story Bible, generate styled text, check style adherence, and more — all directly in the Claude.ai web interface.

Same Tools, Different Connection

The remote MCP server provides the same tools as the local npm package. Choose whichever method works best for your workflow — Claude Desktop with the npm package, or Claude.ai web with the remote server.

OAuth Authentication (Advanced)

For a more seamless connection experience, Claude.ai supports OAuth authentication. Instead of manually adding an API key header, you can use OAuth to let Claude handle authentication automatically.

OAuth Setup (Optional)

Go to Claude.ai > Settings > Connectors
Click Add custom connector
Enter the server URL: https://idioscript.com/api/mcp/remote
Click Advanced settings
Enter your OAuth Client ID and Client Secret (if you have pre-registered credentials)
Save and start a new conversation
Claude will redirect you to Idioscript to authorize access

Note: If you don't provide client credentials, Claude will use Dynamic Client Registration to automatically create them. Either way, you'll be prompted to log in and authorize access.

Other MCP Clients

Any MCP-compatible client can connect to Idioscript using one of two methods:

Option 1: Local npm Package (stdio transport)

Best for desktop applications like Claude Desktop, Cursor, or VS Code.

Configure your MCP client to run npx idioscript-mcp
Set the MCP_API_KEY and MCP_API_BASE_URL environment variables
Connect and start using the tools

Option 2: Remote HTTP Server

Best for web-based clients or environments where npm isn't available.

Configure your client to connect to https://idioscript.com/api/mcp/remote
Add the X-MCP-API-Key header with your API key
Connect and start using the tools

Specific setup will vary by client. Check your client's documentation for details on adding custom MCP servers.

Direct CLI Usage

You can also run the local server directly for testing:

MCP_API_KEY=idi_live_your-key MCP_API_BASE_URL=https://idioscript.com npx idioscript-mcp

Use Cases

Ask Claude about your story while writing in your preferred environment

Generate styled text directly in your IDE

Check style adherence while editing in VS Code

Research your world while drafting in Obsidian

Use Idioscript tools in custom AI workflows

Troubleshooting

Connection Issues

Verify your API key is correct and not revoked
Check that MCP_API_BASE_URL is set to the correct URL
Ensure you have an internet connection
Check Claude Desktop logs for error messages

Server Not Starting

Make sure Node.js is installed (v18+ recommended)
Check that your config file syntax is valid JSON
Try running npx idioscript-mcp directly in a terminal to see error messages
Ensure both environment variables are set correctly

Tools Not Working

Make sure you have at least one project in Idioscript
Verify your project has a generated Style Fingerprint
Check that your API key has access to the project