Troubleshooting

Find solutions to common MCP Studio issues and answers to frequently asked questions.

Need More Help? If you can't find the answer here, contact DarcyIQ support through the help menu in the application.

Common Issues

Deployment Issues

Deployment Fails During Validation

Symptoms:

Deployment stops at "Validating" status
Error message about code validation

Causes & Solutions:

Cause

Solution

Syntax errors in code

Fix errors highlighted in the Build tab editor

Missing imports

Add required import statements

No tools defined

Ensure at least one @app.tool() decorated function exists

Invalid tool signatures

Check function parameters and return types

Example Fix:

# Before (Error: Invalid return type)
@app.tool()
async def my_tool(param: str):
    return "Hello"

# After (Correct)
@app.tool()
async def my_tool(param: str) -> list[TextContent]:
    return [TextContent(type="text", text="Hello")]

Deployment Fails During Build

Symptoms:

Deployment stops at "Building" status
Error message about dependencies or container build

Causes & Solutions:

Cause

Solution

Invalid dependency version

Use valid package versions (e.g., requests>=2.28.0)

Package doesn't exist

Verify package name on PyPI or npm

Conflicting dependencies

Check for version conflicts between packages

Missing runtime detection

Ensure code structure matches Python or Node.js patterns

Specifying Dependencies (Python):

# requirements:
# requests>=2.28.0
# httpx>=0.24.0
# pandas>=2.0.0

from mcp.server import Server
# ... rest of code

Deployment Fails During Deploy

Symptoms:

Deployment stops at "Deploying" status
Timeout or infrastructure errors

Causes & Solutions:

Cause

Solution

Temporary infrastructure issue

Wait a few minutes and retry

Resource limits exceeded

Simplify your code or contact support

Network timeout

Check for extremely large dependencies

Retry: Most "Deploying" failures are temporary. Click Deploy again after a few minutes.

Missing Required Secrets

Symptoms:

Deployment fails with "Missing required secrets" error
Error lists specific environment variable names

Solution:

Navigate to the Build tab
Scroll to the Secrets section
Fill in values for all fields marked as "Required"
Retry deployment

Connection Issues

Integration Not Appearing in Chat

Symptoms:

Deployed integration not available as a tool in Chat
AI doesn't recognize the integration

Causes & Solutions:

Cause

Solution

Integration not enabled

Go to Connect tab and toggle "Enable for Darcy"

Deployment not complete

Verify status shows "Deployed"

Cache delay

Wait 1-2 minutes or refresh the page

Permission issues

Ensure you have access to the integration

API Key Authentication Errors

Symptoms:

External connections return 401 or 403 errors
"Unauthorized" or "Forbidden" messages

Causes & Solutions:

Cause

Solution

Incorrect API key

Copy the key again from the Connect tab

Key not included in header

Use Authorization: Bearer YOUR_KEY header

Key expired or revoked

Check if deployment was modified

Correct Authentication Example:

import httpx

headers = {
    "Authorization": "Bearer mcp_key_xxxxx",  # Include "Bearer " prefix
    "Content-Type": "application/json"
}

response = await client.post(endpoint, headers=headers, json=data)

Connection Timeout Errors

Symptoms:

Requests to external APIs time out
"Connection timed out" errors in logs

Causes & Solutions:

Cause

Solution

External API is slow

Increase timeout in your code

Network restrictions

Verify the external API is accessible

Firewall blocking

Contact support for allowlist requests

Increasing Timeout:

async with httpx.AsyncClient(timeout=60.0) as client:  # 60 second timeout
    response = await client.get(url)

Code Issues

Python Import Errors

Symptoms:

Validation fails with import errors
"Module not found" messages

Causes & Solutions:

Cause

Solution

Package not in requirements

Add package to requirements comment block

Typo in import

Check package name spelling

Wrong package name

Verify correct import name (e.g., PIL vs Pillow)

Common Package Import Names:

Package

Import Name

Pillow

from PIL import Image

beautifulsoup4

from bs4 import BeautifulSoup

python-dateutil

from dateutil import parser

PyYAML

import yaml

Node.js Module Errors

Symptoms:

Build fails with module resolution errors
"Cannot find module" messages

Causes & Solutions:

Cause

Solution

ESM vs CommonJS mismatch

Use consistent import style

Missing package.json

Add package.json comment block

Package not available

Check npm for correct package name

ESM Import Style (Recommended):

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import axios from "axios";

Runtime Not Detected

Symptoms:

Editor shows "Unknown runtime"
Deployment fails with runtime error

Causes & Solutions:

Cause

Solution

No clear language indicators

Add standard imports for your language

Mixed language code

Use only one language per MCP

Empty file

Add minimum required code structure

Minimum Python Structure:

from mcp.server import Server
from mcp.types import TextContent

app = Server("my-server")

@app.tool()
async def hello() -> list[TextContent]:
    return [TextContent(type="text", text="Hello")]

if __name__ == "__main__":
    app.run()

Tool Execution Issues

Tool Returns Errors

Symptoms:

Tool invocation fails with exceptions
Error messages in Chat or logs

Debugging Steps:

Check Logs: Go to Monitor tab and review recent logs
Test Locally: Use the Test panel in the Build tab
Review Code: Look for unhandled exceptions

Adding Error Handling:

@app.tool()
async def safe_tool(param: str) -> list[TextContent]:
    try:
        result = await some_operation(param)
        return [TextContent(type="text", text=result)]
    except ValueError as e:
        return [TextContent(type="text", text=f"Invalid input: {str(e)}")]
    except Exception as e:
        return [TextContent(type="text", text=f"Error: {str(e)}")]

Tool Not Being Selected by AI

Symptoms:

AI doesn't use your tool when it should
Tool available but ignored in conversations

Causes & Solutions:

Cause

Solution

Poor tool description

Write clear, specific docstrings

Ambiguous tool name

Use descriptive, action-oriented names

Too many similar tools

Consolidate or differentiate tools

Good Tool Documentation:

@app.tool()
async def search_customers_by_email(email: str) -> list[TextContent]:
    """
    Search for customers in the CRM using their email address.
    
    Use this tool when you need to find customer information and you have
    their email address. Returns customer details including name, company,
    and recent activity.
    
    Args:
        email: The customer's email address to search for
    
    Returns:
        Customer profile with contact information and history
    """

Frequently Asked Questions

General Questions

What programming languages does MCP Studio support?

MCP Studio supports two runtimes:

Runtime

Language

Version

Python

Python

3.11+

Node.js

JavaScript/TypeScript

18+

How many MCPs can I deploy?

The number of deployable MCPs depends on your DarcyIQ plan. Contact your administrator or check your plan details for specific limits.

No, MCP integrations are scoped to a single organization. To use the same integration in multiple organizations, you would need to:

Export the code from one organization
Create a new MCP in the target organization
Import/paste the code

How do I update a deployed MCP?

To update a deployed integration:

Open the MCP in the builder
Make your changes in the Build tab
Test using the Test panel
Go to Deploy tab and click Redeploy

The new version will replace the current deployment. There may be a brief interruption (a few seconds) during the update.

What's the difference between Custom and Catalog MCPs?

Aspect

Custom MCPs

Catalog MCPs

Source

You write the code

Pre-built from Docker Hub

Customization

Full control

Configuration only

Setup Time

15-30 minutes

2-5 minutes

Code Required

Yes

Validation

Required

Skipped (pre-validated)

Security Questions

How are secrets stored?

Secrets in MCP Studio are:

Encrypted at rest using industry-standard encryption
Never exposed in code or logs
Stored separately from your integration code
Accessible only during runtime execution
Not visible to viewers (only owners and editors)

Can others see my integration code?

Code visibility depends on permission level:

Permission

Can View Code

Can Edit Code

Owner

Yes

Editor

Yes

Viewer

Yes

To completely hide your code, don't share the integration with Viewer permissions.

Are my API keys safe?

Yes. API keys and secrets are:

Stored encrypted, separate from code
Never logged or displayed after entry
Injected as environment variables at runtime
Not accessible via the API endpoint

Best Practice: Create dedicated API keys for DarcyIQ integrations with minimum required permissions. Rotate keys regularly.

Technical Questions

Why does my integration timeout?

MCP tools have execution time limits. If your tool takes too long, it will timeout.

Solutions:

Issue

Solution

Slow external API

Increase timeout, optimize queries

Large data processing

Process data in chunks

Network latency

Use connection pooling

Complex computations

Simplify or offload to external service

Can I use external packages?

Yes! You can use most Python (PyPI) and Node.js (npm) packages.

Python: Add dependencies to a comment block at the top of your file:

# requirements:
# requests>=2.28.0
# pandas>=2.0.0

Node.js: Dependencies are auto-detected from imports, or specify in a comment:

/* package.json:
{
  "dependencies": {
    "axios": "^1.4.0"
  }
}
*/

How do I debug my integration?

Debugging Tools:

Method

How To

Test Panel

Use Build tab test panel for quick testing

Logs

View real-time logs in Monitor tab

Print Statements

Add print() statements (appear in logs)

Try/Except

Wrap code in try/except to catch errors

Example Debug Logging:

@app.tool()
async def my_tool(param: str) -> list[TextContent]:
    print(f"Tool called with param: {param}")  # Appears in logs
    
    try:
        result = await some_operation(param)
        print(f"Operation successful: {result}")
        return [TextContent(type="text", text=result)]
    except Exception as e:
        print(f"Error occurred: {str(e)}")  # Appears in logs
        return [TextContent(type="text", text=f"Error: {str(e)}")]

What happens if my integration crashes?

If an MCP tool crashes:

The error is logged (visible in Monitor tab)
An error message is returned to the user
The integration remains available for future calls
Other tools in the same MCP are unaffected

The integration does NOT need to be redeployed after a crash—it automatically recovers.

Billing Questions

Does MCP Studio cost extra?

MCP Studio availability and limits depend on your DarcyIQ plan. Check with your administrator or account manager for plan-specific details.

Are there limits on tool invocations?

Tool invocation limits may apply depending on your plan. Monitor your usage in the DarcyIQ dashboard.

Error Reference

Validation Errors

Error Code

Message

Solution

VAL001

No tools defined

Add at least one @app.tool() function

VAL002

Invalid return type

Return list[TextContent]

VAL003

Missing docstring

Add docstring to tool function

VAL004

Syntax error

Fix code syntax errors

VAL005

Import error

Add missing packages to requirements

Deployment Errors

Error Code

Message

Solution

DEP001

Build failed

Check package versions and imports

DEP002

Missing secrets

Configure all required secrets

DEP003

Deployment timeout

Retry after a few minutes

DEP004

Resource limit exceeded

Simplify code or contact support

Runtime Errors

Error Code

Message

Solution

RUN001

Tool execution failed

Check logs for exception details

RUN002

Timeout exceeded

Optimize tool or increase timeout

RUN003

Authentication failed

Verify secrets are correct

RUN004

External service error

Check external API status

Getting More Help

If you can't resolve your issue:

Check Logs: Monitor tab shows detailed error information
Review Documentation: Other pages may have specific guidance
Contact Support: Use the help menu in DarcyIQ

Resource

Best For

MCP Studio Overview

General feature understanding

Building Custom MCPs

Development guidance

Code Samples

Working examples

MCP Protocol Docs

Technical MCP specification

PreviousCode Samples NextIntegrations

Last updated 5 months ago

Was this helpful?

Common Issues

Deployment Issues

Deployment Fails During Validation

Deployment Fails During Build

Deployment Fails During Deploy

Missing Required Secrets

Connection Issues

Integration Not Appearing in Chat

API Key Authentication Errors

Connection Timeout Errors

Code Issues

Python Import Errors

Node.js Module Errors

Runtime Not Detected

Tool Execution Issues

Tool Returns Errors

Tool Not Being Selected by AI

Frequently Asked Questions

General Questions

What programming languages does MCP Studio support?

How many MCPs can I deploy?

Can I share MCPs across organizations?

How do I update a deployed MCP?

What's the difference between Custom and Catalog MCPs?

Security Questions

How are secrets stored?

Can others see my integration code?

Are my API keys safe?

Technical Questions

Why does my integration timeout?

Can I use external packages?

How do I debug my integration?

What happens if my integration crashes?

Billing Questions

Does MCP Studio cost extra?

Are there limits on tool invocations?

Error Reference

Validation Errors

Deployment Errors

Runtime Errors

Getting More Help