Overview

The Zylo MCP Server enables AI assistants (Claude, ChatGPT, etc.) to interact directly with your Zylo data through natural language. Query your SaaS portfolio, update resources, and generate insights and reports -- all through conversation.

Key Benefits

Natural Language Interface: Ask questions about your SaaS portfolio in plain language
Direct Data Access: AI assistants query your Zylo data in real-time
Powerful Querying: Build complex multi-resource queries using Zylo's Report Builder
Generate Insights: Create reports, graphs and charts, or have your AI recommend an action plan
Safe Operations: Granular permissions control what your AI can read and modify
Secure Communication: All data transmitted over TLS with OAuth or API key authentication

How It Works

The Zylo MCP Server uses the Model Context Protocol (MCP) Streamable HTTP transport to connect AI assistants to your Zylo data:

You ask a question in natural language to your AI assistant
AI determines which tools to use based on your question
Client connects to https://api.zylo.com/mcp using OAuth or your API key
MCP Server authenticates your request and checks permissions
Server executes the operation (query data, create resource, etc.)
Results are returned to the AI assistant via JSON or SSE
AI formats the response into a readable answer for you

Before You Start - Prerequisites

Choose an authentication method

The Zylo MCP server supports two authentication methods: OAuth 2.0 with PKCE, and API tokens. General guidance is below, but for help in determining the best method for your use case, contact your Zylo admin.

OAuth 2.0 with PKCE

If using OAuth for authentication, a Zylo admin will have to ensure the relevant Zylo user has appropriate permissions and the MCP role. Simply configure your client with the Zylo MCP Server URL (https://api.zylo.com/mcp), and when starting the first conversation, your client will open a browser window for you to sign into Zylo and authorize the MCP connection.
Best for desktop clients (e.g. Claude Desktop) and IDEs (e.g. VSCode)
Inherits permissions from the specified Zylo user account
Access tokens are short-lived (5mins) and refresh automatically.

API Key

If using an API key for authentication, a Zylo admin will have to create/scope the API key via the Company Tokens tab within the admin panel. The complete API key combines the token_id and token_secret with a colon separator (token_id:token_secret). Note that lost token secrets cannot be recovered, so be sure to record it when creating the API key.
Best for automation and CLI tools (e.g. Claude Code)
Permissions are assigned via independent API keys rather than a user account
API keys require manual configuration and rotation

Other requirements

An MCP-compatible client must be used to interact with the MCP server.
The latest version of Node.js may be required for some MCP clients (e.g. Claude Desktop). Check your MCP client's official documentation to confirm.
In general, models from major labs (Google, Anthropic, OpenAI) will perform best. Use lower-tier models with caution (e.g. Haiku), as they're more prone to hallucination when interacting with any MCP server.

MCP Client Configuration

Be sure to consult the official documentation for your client and the official Model Context Protocol Documentation. The guides below may be helpful in configuring some of the more popular clients, but information from official documentation supersedes these guides.

MCP Setup Guide for Claude
MCP Setup Guide for ChatGPT
VS Code - Depending on the authentication method being used, add one of the below configs to .vscode/mcp.json.

For OAuth: Note that VS Code will handle the OAuth PKCE flow automatically — a browser window will open for you to sign in on first use.
```
{
  "servers": {
    "zylo": {
      "type": "http",
      "url": "https://api.zylo.com/mcp"
    }
  }
}
```
For API Key:
As best practice, we recommend storing your API key in a secure vault and calling it via an environmental variable rather than configuring it in plaintext as shown in the example below. For assistance with those configurations, contact your IT or InfoSec admin.
```
{
  "servers": {
    "zylo": {
      "type": "http",
      "url": "https://api.zylo.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_ID:YOUR_TOKEN_SECRET"
      }
    }
  }
}
```

Further Reading

Tools Reference details the suite of tools included in the Zylo MCP server.
Data Dictionary details all fields available across Zylo API resources.
Query Examples lists sample queries that can be good starting points for new users.
Query Builder gives a deep-dive into the underlying functionality of how the MCP server formats queries.
The official Model Context Protocol documentation may contain useful details or configuration info for your MCP-compatible client.

Common Troubleshooting Tips

Authentication Failed

Common Cause: Invalid or missing API key
Common Solution: Verify your API key format ({token_id}:{token_secret}), and have a Zylo admin check to make sure the key hasn't been revoked in the Zylo admin panel

Permission Denied

Common Cause: The API key doesn't have permission for the requested operation
Common Solution: Ensure you're using the correct key (if there are multiple), and have a Zylo admin check the key's permissions in the Zylo admin panel

Connection Timeout

Common Cause: Network connectivity issues or server unavailable
Common Solution: Verify the MCP server URL is correct, verify that your network is stable, and check status.zylo.com for temporary outage

Query Timeout

Common Cause: Your query is taking too long (>30 seconds).
Common Solutions:
- Add more specific filters (date ranges, status, etc.)
- Reduce the number of fields requested
- Query smaller date ranges
- Break complex queries into smaller ones

Not Found

Common Cause: The resource you're trying to update doesn't exist.
Common Solutions:
- Verify the resource ID is correct
- Query for the resource first to confirm it exists
- Check if the resource was deleted

AI Assistant Not Using Tools

Common Cause: MCP configuration issue
Common Solution: Restart your AI assistant application, verify MCP configuration file syntax, check MCP server logs for errors, and ensure API key is properly formatted