# Troubleshooting

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

{% hint style="info" %}
**Need More Help?** If you can't find the answer here, contact DarcyIQ support through the help menu in the application.
{% endhint %}

## 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:**

```python
# 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):**

```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 |

{% hint style="info" %}
**Retry**: Most "Deploying" failures are temporary. Click Deploy again after a few minutes.
{% endhint %}

***

#### 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:**

```python
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:**

```python
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):**

```javascript
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:**

```python
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:**

```python
@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:**

```python
@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

{% hint style="warning" %}
**Best Practice**: Create dedicated API keys for DarcyIQ integrations with minimum required permissions. Rotate keys regularly.
{% endhint %}

***

### 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:

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

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

```javascript
/* 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:**

```python
@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](/integrations-and-configuration/mcp-studio.md)                       | General feature understanding |
| [Building Custom MCPs](/integrations-and-configuration/mcp-studio/building-custom-mcps.md) | Development guidance          |
| [Code Samples](/integrations-and-configuration/mcp-studio/mcp-studio-samples.md)           | Working examples              |
| [MCP Protocol Docs](https://modelcontextprotocol.io)                                       | Technical MCP specification   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.darcyiq.com/integrations-and-configuration/mcp-studio/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.