> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging Integrations

> How to debug MCP integration issues

## Overview

Learn how to identify and fix issues with your MCP integrations.

## Debugging Tools

> [card] MCP Logs
>
> View server request logs

> [card] AI teammate Insights
>
> See tool usage analytics

> [card] Builder chat
>
> Test tools interactively

## Accessing Logs

### MCP Server Logs

View all requests to your MCP server:

**1. Go to Logs**

**Dashboard -> MCP Servers -> Your Server -> Logs**

**2. Review Requests**

See all tool calls:

* Timestamp
* Tool name
* Parameters
* Response
* Status (success/error)
* Duration

**3. Filter**

Filter logs by:

* Date range
* Tool name
* Status (success/error)
* AI teammate

### AI teammate Tool Logs

View tools used by specific AI teammate:

**1. Open your AI teammate**

Go to your AI teammate

**2. Insights Tab**

Click **Insights** tab

**3. Tool Analytics**

See:

* Which tools were called
* Success/failure rates
* Response times
* Error messages

## Common Issues

### Authentication Errors

**Symptom:** 401 Unauthorized or 403 Forbidden

**Causes:**

* Invalid API key
* Expired token
* Wrong authentication method
* Missing credentials

**Debug:**

**1. Check Credentials**

**Dashboard -> AI teammates -> Your AI teammate -> Tools -> Your Tool**

Verify:

* API key is correct
* Auth method matches API requirements
* Credentials not expired

**2. Test API Directly**

```bash theme={null}
# Test with curl
curl https://api.example.com/users \
  -H "Authorization: Bearer YOUR_TOKEN"
```

If this fails, the issue is with your credentials

**3. Check Logs**

Look for auth errors in MCP server logs

**4. Fix**

Update credentials in AI teammate tool settings and test again

### Tool Not Found

**Symptom:** "Tool not available" error

**Causes:**

* Tool not in OpenAPI spec
* MCP server not connected to AI teammate
* Tool name mismatch

**Debug:**

**1. Check Connection**

**AI teammate -> Tools Tab**

Verify MCP server is connected and showing tools

**2. Check Tool Name**

Tool names are generated from endpoint paths:

* `GET /users` -> `get_users`
* `POST /customers` -> `create_customer`

Check if expected tool name matches

**3. Refresh**

Disconnect and reconnect AI teammate tool to refresh tools

### Slow Responses

**Symptom:** Tools taking >5 seconds

**Causes:**

* Slow API responses
* Large data transfers
* Network issues
* No caching

**Debug:**

**1. Check Response Times**

**Dashboard -> MCP Servers -> Logs**

Look at duration column

**2. Test API Speed**

```bash theme={null}
# Time API call
time curl https://api.example.com/users
```

**3. Identify Slow Endpoints**

Find which tools are slowest in logs

**4. Fix**

Options:

* Optimize API queries
* Add caching
* Paginate large results
* Use async processing

### Invalid Parameters

**Symptom:** "Invalid parameter" or "Required parameter missing"

**Causes:**

* Missing required field
* Wrong parameter type
* Invalid format

**Debug:**

**1. Check Logs**

Look for parameter validation errors

**2. Review OpenAPI Spec**

Verify parameter definitions:

```yaml theme={null}
parameters:
  - name: email
    required: true
    schema:
      type: string
      format: email
```

**3. Test in the builder chat**

Try tool with different parameter combinations:

```text theme={null}
"Create customer John, john@test.com"
vs
"Create customer John"
```

**4. Fix**

Update OpenAPI spec with correct parameter requirements

### Rate Limiting

**Symptom:** 429 Too Many Requests

**Causes:**

* Exceeded API rate limits
* Too many concurrent requests
* No rate limit handling

**Debug:**

**1. Check Rate Limits**

Review API documentation for limits

**2. Monitor Request Volume**

**Dashboard -> MCP Servers -> Analytics**

Check requests per minute

**3. Review Logs**

Look for 429 errors and their timing

**4. Fix**

Options:

* Implement exponential backoff
* Add request queuing
* Cache responses
* Upgrade API plan

## Debugging Workflow

### Step 1: Reproduce

Reproduce the issue consistently:

```text theme={null}
1. Open the builder chat
2. Send exact same request
3. Observe error

Example:
"Create customer john@test.com"
-> Error: "Email already exists"
```

### Step 2: Check Logs

Review MCP server logs:

```text theme={null}
Timestamp: 2025-01-05 10:30:15
Tool: create_customer
Parameters: { email: "john@test.com", name: "John" }
Response: { success: false, error: "Email already exists" }
Status: Error
Duration: 234ms
```

### Step 3: Test Directly

Test the underlying API directly:

```bash theme={null}
# Replicate the exact call
curl -X POST https://api.example.com/customers \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@test.com", "name": "John"}'
```

### Step 4: Isolate

Narrow down the issue:

* Is it authentication? Test with different credentials
* Is it the API? Test API directly
* Is it the MCP server? Check other tools
* Is it your AI teammate? Test with different AI teammate

### Step 5: Fix

Apply the appropriate fix:

```text Authentication Issue theme={null}
Dashboard -> MCP Servers -> Settings
-> Update API credentials
```

```text API Issue theme={null}
Contact API provider or
review API documentation
```

```text OpenAPI Spec Issue theme={null}
Dashboard -> MCP Servers -> Edit
-> Update OpenAPI spec
```

```text Teammate Issue theme={null}
Teammate -> Settings -> Reset
-> Reconnect tools
```

### Step 6: Verify

Test the fix:

```text theme={null}
1. Apply fix
2. Test in the builder chat
3. Check logs for success
4. Monitor for 24 hours
```

## Advanced Debugging

### Enable Verbose Logging

Get more detailed logs:

**Dashboard -> MCP Servers -> Your Server -> Settings**

* Enable **Debug Mode**
* Shows full request/response bodies
* Includes headers and metadata

### Webhook Debugging

For webhooks, test delivery:

```bash theme={null}
# Use webhook.site for testing
1. Go to webhook.site
2. Copy unique URL
3. Set as webhook URL in MCP server
4. Trigger event
5. See exact payload received
```

### Network Debugging

Check network issues:

```bash theme={null}
# Test connectivity
ping api.example.com

# Check DNS
nslookup api.example.com

# Trace route
traceroute api.example.com

# Test SSL
openssl s_client -connect api.example.com:443
```

## Debugging Checklist

When debugging an issue:

* [ ] Can you reproduce it consistently?
* [ ] What's in the error logs?
* [ ] Does the API work directly?
* [ ] Is authentication correct?
* [ ] Are parameters valid?
* [ ] Is the network reachable?
* [ ] Are there rate limits?
* [ ] Is the OpenAPI spec correct?
* [ ] Have you tested in the builder chat?
* [ ] Have you checked recent changes?

## Getting Help

If you're still stuck:

### Check Documentation

* [OpenAPI Import](/docs/integrations/custom/openapi.md)
* [Authentication](/docs/integrations/custom/authentication.md)
* [Best Practices](/docs/integrations/guides/best-practices.md)

### Contact Support

**[hello@boostgpt.co](mailto:hello@boostgpt.co)**

Include:

* MCP server ID
* Error message
* Steps to reproduce
* Logs (from Dashboard -> MCP Servers -> Logs)
* OpenAPI spec or Postman collection

### Community

Join our Discord for community help:

* [discord.gg/boostgpt](https://discord.gg/KGhz5SnyXM)

## Next Steps

> [card] [Testing Guide](/docs/integrations/guides/testing.md)
>
> Learn how to test integrations

> [card] [Best Practices](/docs/integrations/guides/best-practices.md)
>
> Follow integration best practices


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.