Theneo MCP Server

Model Context Protocol server for Theneo SDK - The automation backbone for API documentation in the AI era.

This MCP server exposes Theneo's API documentation platform through the Model Context Protocol, allowing AI assistants to create, update, and publish API documentation automatically.

Overview

Theneo MCP enables any AI assistant (Claude Desktop, VS Code Copilot, Cursor, etc.) to interact with Theneo's SDK, making API documentation creation and maintenance fully automatable. Perfect for CI/CD pipelines, AI-driven workflows, and developer productivity tools.

Key Features

• 💬 Natural Language: Just talk—no need to memorize tool names or parameters!

• 🎯 Name-Based References: Reference projects and workspaces by name instead of IDs—AI looks them up automatically!

• 🤖 AI-First: Works with any MCP-compatible AI assistant (Claude, VS Code, Cursor)

• 🔐 Enterprise Security: Multi-source config, OS keychain support, secret masking

• 🛠️ 15 Powerful Tools: Complete project lifecycle management—workspaces, projects, versions, exports, and more

• 📦 Flexible Input: Supports OpenAPI/Swagger files, URLs, raw text, and Postman collections

• 🚀 AI-Powered: Built-in AI description generation (fill, overwrite, or skip)

• 🔄 Smart Imports: Merge, overwrite, or endpoints-only update strategies

• 🌍 Profile Support: Manage multiple environments (dev, staging, prod)

Design Choices

Why SDK Over CLI?

Direct SDK integration provides type safety, better error handling, and access to the full API surface without shell escaping issues.

Why OS Keychain?

Secure at-rest storage for credentials without environment variables or plain-text files. Cross-platform support via keytar.

Why Profile Support?

Multi-environment workflows (dev/staging/prod) are common. Profiles allow easy context switching without credential juggling.

Why MCP Protocol?

MCP standardizes AI-tool integration. Write once, works with Claude, VS Code Copilot, Cursor, and future AI assistants.

Installation

npm (Recommended)

Homebrew (macOS/Linux)

Docker

See DOCKER.md for detailed Docker usage.

Local Development

Quick Start (5 Minutes)

1. Get Your API Key

Visit https://app.theneo.io/ to get your Theneo API key.

2. Configure Authentication

Option A: OS Keychain (Recommended for local dev)

Option B: Environment Variable

3. Connect to Your AI Assistant

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

VS Code Copilot

Add to your VS Code settings.json:

Cursor

Add to Cursor settings (Settings → MCP):

4. Test It Out

In your AI assistant, just talk naturally:

Then create a project:

Or if you prefer being explicit:

💡 Pro tip: You don't need to memorize tool names or parameters—just describe what you want in plain English!

Configuration

Configuration Sources & Precedence

Configuration is loaded from multiple sources with clear precedence (highest first):

Environment Variables

Project Configuration File

Create .theneo-mcp.yaml or .theneo-mcp.json in your project root:

⚠️ Security Note: Never commit API keys to version control! Store them in keychain or environment variables.

User Configuration

Create ~/.config/theneo-mcp/config.json (Linux/macOS) or %AppData%/theneo-mcp/config.json (Windows):

OS Keychain (Recommended)

Store API keys securely in your system's keychain:

Using Profiles

Switch between environments easily:

Available Tools

💡 Tip: You don't need to use the exact tool names! Just talk naturally to your AI assistant, and it will figure out which tool to call.

🎯 New: You can now reference projects and workspaces by name instead of remembering their IDs! The AI will automatically look them up for you.

1. theneo_list_workspaces

List all workspaces accessible to your account.

Parameters: None

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

2. theneo_list_projects

List all projects in a workspace or across all workspaces. You can filter by workspace using ID, key (slug), or name. Returns project names, IDs, and details.

Parameters:

• workspaceId (string, optional): Workspace ID to filter projects

• workspaceKey (string, optional): Workspace key/slug to filter projects

• workspaceName (string, optional): Workspace name to filter projects

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

3. theneo_create_project

Create a new API documentation project with optional spec import and AI generation. You can specify the workspace by ID, key (slug), or name.

Parameters:

• name (string, required): Project name

• workspaceKey (string, optional): Workspace slug

• workspaceId (string, optional): Workspace ID

• workspaceName (string, optional): Workspace name

• publish (boolean, optional): Publish immediately

• isPublic (boolean, optional): Make project public

• descriptionGeneration (enum, optional): FILL | OVERWRITE | NO_GENERATION

• Data sources (choose one):

  • file (string): Path to local OpenAPI/Swagger file

  • link (string): URL to OpenAPI/Swagger spec

  • text (string): Raw OpenAPI/Swagger spec

  • postmanApiKey + postmanCollectionIds: Import from Postman

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

Example Response:

4. theneo_import_project_document

Import or update API documentation in an existing project. You can reference both the project and workspace by name instead of IDs.

Parameters:

• projectId (string, optional): Target project ID

• projectName (string, optional): Target project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

• publish (boolean, optional): Publish after import

• importOption (enum, optional): MERGE | OVERWRITE | ENDPOINTS_ONLY

• Data sources (same as create_project, one required)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

5. theneo_publish_project

Publish a project to make it live. You can reference both project and workspace by name. Optionally specify a version to publish.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

• versionId (string, optional): Version ID to publish (publishes default version if not specified)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

6. theneo_preview_link

Get the editor preview URL for a project. You can reference both project and workspace by name.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

7. theneo_wait_for_generation

Wait for AI description generation to complete. You can reference both project and workspace by name.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

• retryTimeMs (number, optional): Polling interval (default: 2500)

• maxWaitTimeMs (number, optional): Max wait time (default: 120000)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

8. theneo_get_generation_status

Get the current status and progress of AI description generation for a project. You can reference both project and workspace by name.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

9. theneo_delete_project

Permanently delete a project. You can reference both project and workspace by name. ⚠️ This action cannot be undone.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

10. theneo_list_project_versions

List all versions of a specific project. You can reference both project and workspace by name.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

11. theneo_create_project_version

Create a new version of a project. You can reference both project and workspace by name.

Parameters:

• name (string, required): Version name

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

• previousVersionId (string, optional): Previous version ID to copy from

• isNewVersion (boolean, optional): Whether this is a new version

• isEmpty (boolean, optional): Whether the version should be empty

• isDefault (boolean, optional): Whether this should be the default version

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

12. theneo_delete_project_version

Delete a specific version of a project. ⚠️ This action cannot be undone.

Parameters:

• versionId (string, required): Version ID to delete

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

13. theneo_add_subscriber_to_version

Add an email subscriber to receive updates for a specific project version.

Parameters:

• email (string, required): Email address to subscribe

• projectVersionId (string, required): Project version ID

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

14. theneo_export_project

Export a project's documentation. You can reference both project and workspace by name.

Parameters:

• projectId (string, optional): Project ID

• projectName (string, optional): Project name (alternative to projectId)

• workspaceId (string, optional): Workspace ID (helps when using projectName)

• workspaceKey (string, optional): Workspace key/slug (helps when using projectName)

• workspaceName (string, optional): Workspace name (helps when using projectName)

• versionId (string, optional): Version ID to export

• dir (string, optional): Directory to save export

• noGeneration (boolean, optional): Skip AI generation

• shouldGetPublicViewData (boolean, optional): Get public view data

• openapi (boolean, optional): Export as OpenAPI format

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

15. theneo_list_postman_collections

List all Postman collections accessible with a provided Postman API key.

Parameters:

• postmanApiKey (string, required): Postman API key

Natural Language Examples:

Explicit Tool Call (for testing/debugging):

Demo Script (End-to-End)

This 5-minute demo shows the complete workflow. You can use either natural language or explicit tool calls.

🗣️ Natural Language Version (Recommended)

Just talk naturally to your AI assistant:

🔧 Explicit Tool Calls Version (For Testing)

If you want precise control or are debugging:

💡 Real-World Conversation Example

🎯 Using Names Instead of IDs (No More Copy-Paste!)

One of the most powerful features is the ability to reference both projects and workspaces by name:

The AI will automatically:

1. Resolve workspace name → workspace ID (if needed)

2. Resolve project name → project ID (if needed)

3. Execute the operation

4. Return a friendly message

This works for:

• ✅ Workspace references: ID, key (slug), or name

• ✅ Project references: ID or name

• ✅ All project operations: create, import, publish, preview, delete, export

• ✅ Version management: list, create, delete versions

• ✅ AI generation: wait for completion, check status

• ✅ External integrations: list Postman collections, add subscribers

No more copying and pasting cryptic IDs!

More examples in examples/demo-prompts.md.

Security Best Practices

✅ DO

• Use OS keychain for API keys on local machines

• Use environment variables in CI/CD and containers

• Enable secret masking in your CI logs

• Rotate API keys regularly and after demos

• Use profiles to isolate environments

• Review to exclude secrets

• Use to prevent publishing secrets

❌ DON'T

• Never commit API keys to git

• Never log full configuration objects

• Never use API keys in URLs or query parameters

• Never share API keys in public channels

• Avoid storing keys in project RC files checked into git

CI/CD Integration

Example GitHub Actions workflow:

Security Notes for CI:

• Store THENEO_API_KEY as a GitHub secret

• Use secrets. syntax to avoid exposure

• Consider short-lived tokens if Theneo supports OIDC

• Mask secrets in logs: echo "::add-mask::$THENEO_API_KEY"

Development

Build from Source

Development Mode

Code Quality

Project Structure

Troubleshooting

API Key Not Found

Problem: Server exits with "API key not configured"

Solutions:

1. Set environment variable: export THENEO_API_KEY=your_key

2. Save to keychain: theneo-mcp creds save --apiKey your_key

3. Check profile: theneo-mcp server --profile default

Keychain Not Available

Problem: "OS keychain is not available"

Solution: Use environment variables or config files instead:

MCP Server Not Connecting

Problem: AI assistant can't find tools

Solutions:

1. Restart your AI assistant after config changes

2. Check logs: Look for MCP connection errors

3. Verify command path: Use absolute path to theneo-mcp

4. Test manually: Run theneo-mcp server to see startup logs

Import Fails

Problem: "Failed to import document"

Solutions:

1. Verify file path or URL is accessible

2. Ensure OpenAPI spec is valid JSON/YAML

3. Check project ID is correct

4. Review API key permissions

AI Generation Timeout

Problem: "Generation failed or timed out"

Solutions:

1. Increase timeout: maxWaitTimeMs: 300000 (5 minutes)

2. Check Theneo dashboard for generation status

3. Try again - large specs may take time

Publishing to npm

Pre-Publish Checklist

• Update version in package.json

• Run npm run type-check

• Run npm run lint

• Test build: npm run build

• Verify .npmignore excludes secrets

• Test installation: npm pack and install locally

• Update CHANGELOG.md

Publish

What Gets Published

✅ Included:

• Compiled JavaScript (dist/)

• Package metadata (package.json)

• Documentation (README.md, LICENSE)

❌ Excluded (via .npmignore):

• TypeScript source (src/)

• Test files and coverage (src/__tests__/, coverage/, *.test.ts)

• Environment files (.env, .env.*)

• Example configurations with potential secrets (.theneo-mcp.json, .theneo-mcp.yaml)

• Development configs (tsconfig.json, vitest.config.ts, eslint.config.js)

• CI/CD configs (.github/, GitHub Actions workflows)

• Docker files (Dockerfile, .dockerignore)

• IDE settings (.vscode/, .idea/)

Security Note: The .npmignore file is configured to exclude all potentially sensitive files. Always review before publishing:

Testing

This project has comprehensive test coverage with both unit and integration tests.

Telemetry

Theneo MCP includes optional, privacy-first telemetry to help improve the tool. Telemetry is:

• ✅ Opt-in - Disabled by default

• ✅ Anonymous - No personal data collected

• ✅ Local - Data stored on your machine

• ✅ Transparent - View anytime with theneo-mcp telemetry status

CI/CD

The project includes comprehensive GitHub Actions workflows:

• CI: Runs tests on Node 18, 20, 22 for every push/PR

• Release: Automatically publishes to npm and updates Homebrew on version tags

• Quality: Weekly security audits and dependency checks

See .github/workflows/ for workflow details.

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Write tests for new functionality

4. Ensure all checks pass: npm test

5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE file for details

Links

• Theneo Platform: https://theneo.io

• Theneo SDK: https://www.npmjs.com/package/@theneo/sdk

• Model Context Protocol: https://modelcontextprotocol.io

• Issues: https://github.com/atombreak/theneo-mcp/issues

Support

• Documentation: This README and examples/demo-prompts.md

• Issues: GitHub Issues

• Theneo Support: https://theneo.io/support

Made with ❤️ for the AI-powered documentation era

Positioning Theneo as the automation backbone for developer documentation