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:

1. Navigate to the Build tab

2. Scroll to the Secrets section

3. Fill in values for all fields marked as "Required"

4. 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:

1. Check Logs: Go to Monitor tab and review recent logs

2. Test Locally: Use the Test panel in the Build tab

3. 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.

---

Can I share MCPs across organizations?

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

1. Export the code from one organization

2. Create a new MCP in the target organization

3. Import/paste the code

---

How do I update a deployed MCP?

To update a deployed integration:

1. Open the MCP in the builder

2. Make your changes in the Build tab

3. Test using the Test panel

4. 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	No
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	Yes
Editor	Yes	Yes
Viewer	Yes	No

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:

1. The error is logged (visible in Monitor tab)

2. An error message is returned to the user

3. The integration remains available for future calls

4. 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:

1. Check Logs: Monitor tab shows detailed error information

2. Review Documentation: Other pages may have specific guidance

3. 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