# Connector Setup Guides

div
strong
🔨 In Development
 — This section is still being developed and may change.


Step-by-step guides for setting up each personal connector.

## GitHub

### Prerequisites

- GitHub account
- Repository access


### Step 1: Generate Personal Access Token

1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
2. Click **"Generate new token (classic)"**
3. Name: `Freddy AI Integration`
4. Select scopes:
  - ✅ `repo` - Full control of private repositories
  - ✅ `read:org` - Read organization data
  - ✅ `workflow` - Update GitHub Actions workflows
5. Click **"Generate token"**
6. **Copy the token** (starts with `ghp_`)


### Step 2: Configure in Freddy


```bash
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations \
  -H "api-key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "github",
    "name": "My GitHub",
    "configuration": {
      "defaultRepo": "username/repository"
    },
    "credentials": {
      "token": "ghp_your_token_here"
    }
  }'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/personal-connectors/configurations",
    headers={
        "api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "connectorId": "github",
        "name": "My GitHub",
        "configuration": {
            "defaultRepo": "username/repository"
        },
        "credentials": {
            "token": "ghp_your_token_here"
        }
    }
)

print(response.json())
```

### Step 3: Test Connection


```bash
curl -X POST https://api.freddy.aitronos.com/v1/personal-connectors/configurations/{config_id}/test \
  -H "api-key: $FREDDY_API_KEY"
```

**Expected response:**


```json
{
  "configurationId": "pconf_abc123",
  "status": "healthy",
  "message": "Connection successful"
}
```

### Available Tools

Once configured, your assistant can:

- Create issues
- List issues and pull requests
- Create pull requests
- Add comments
- Manage labels
- Search repositories


## ClickUp

### Prerequisites

- ClickUp account
- Workspace access


### Step 1: Generate API Token

1. Go to [ClickUp Settings → Apps](https://app.clickup.com/settings/apps)
2. Scroll to **"API Token"**
3. Click **"Generate"** or **"Regenerate"**
4. **Copy your API token** (starts with `pk_`)


### Step 2: Get Workspace and List IDs

1. Open ClickUp and navigate to your workspace
2. Click on a list
3. Copy the list ID from the URL: `https://app.clickup.com/{workspace_id}/v/li/{list_id}`


### Step 3: Configure in Freddy


```bash
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations \
  -H "api-key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "clickup",
    "name": "My ClickUp",
    "configuration": {
      "workspaceId": "12345678",
      "defaultListId": "987654321"
    },
    "credentials": {
      "apiKey": "pk_your_clickup_api_key"
    }
  }'
```


```python
response = requests.post(
    "https://api.freddy.aitronos.com/v1/personal-connectors/configurations",
    headers={
        "api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "connectorId": "clickup",
        "name": "My ClickUp",
        "configuration": {
            "workspaceId": "12345678",
            "defaultListId": "987654321"
        },
        "credentials": {
            "apiKey": "pk_your_clickup_api_key"
        }
    }
)
```

### Available Tools

- Create tasks
- List tasks
- Update tasks
- Delete tasks
- Add comments
- Manage priorities


## Jira

### Prerequisites

- Atlassian account
- Jira project access


### Step 1: Generate API Token

1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **"Create API token"**
3. Label: `Freddy AI`
4. Click **"Create"**
5. **Copy the token**


### Step 2: Get Your Jira Details

- **Domain:** Your Jira site URL (e.g., `yourcompany.atlassian.net`)
- **Email:** Your Atlassian account email
- **Project Key:** Found in your project settings


### Step 3: Configure in Freddy


```bash
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations \
  -H "api-key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "jira",
    "name": "My Jira",
    "configuration": {
      "domain": "yourcompany.atlassian.net",
      "defaultProject": "PROJ"
    },
    "credentials": {
      "email": "your.email@company.com",
      "apiToken": "your_jira_api_token"
    }
  }'
```


```python
response = requests.post(
    "https://api.freddy.aitronos.com/v1/personal-connectors/configurations",
    headers={
        "api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "connectorId": "jira",
        "name": "My Jira",
        "configuration": {
            "domain": "yourcompany.atlassian.net",
            "defaultProject": "PROJ"
        },
        "credentials": {
            "email": "your.email@company.com",
            "apiToken": "your_jira_api_token"
        }
    }
)
```

### Available Tools

- Create issues
- List issues (with JQL support)
- Update issues
- Transition issues (change status)
- Add comments
- Manage assignees


## Microsoft Teams (Coming Soon)

OAuth integration for Microsoft Teams is coming soon.

## Custom MCP Server

### Prerequisites

- Running MCP server
- Server URL and credentials


### Step 1: Prepare Your MCP Server

Your server must implement the MCP protocol:


```python
# Example MCP server endpoints
GET  /mcp/tools      # List available tools
POST /mcp/execute    # Execute a tool
GET  /health         # Health check
```

### Step 2: Configure in Freddy


```bash
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations \
  -H "api-key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "custom",
    "name": "My Custom Server",
    "configuration": {
      "serverUrl": "https://my-mcp-server.com",
      "serverType": "http"
    },
    "credentials": {
      "apiKey": "your_custom_api_key"
    }
  }'
```

### MCP Protocol Requirements

Your server must respond to:

**GET /mcp/tools**


```json
{
  "tools": [
    {
      "name": "my_tool",
      "description": "Tool description",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": { "type": "string" }
        },
        "required": ["param1"]
      }
    }
  ]
}
```

**POST /mcp/execute**


```json
{
  "tool": "my_tool",
  "arguments": { "param1": "value" },
  "_credentials": { "apiKey": "..." }
}
```

**GET /health**


```json
{
  "status": "healthy"
}
```

## Troubleshooting

### Configuration Fails Validation

**Error:** `Failed to validate credentials`

**Solutions:**

1. Verify token/API key is correct
2. Check token hasn't expired
3. Ensure token has required permissions
4. Test token directly with service API


### Configuration Shows "Unhealthy"

**Error:** Configuration created but marked unhealthy

**Solutions:**

1. Check `lastError` field for details
2. Test connection manually
3. Verify service is accessible
4. Update credentials if expired


### Tools Not Discovered

**Error:** No tools available

**Solutions:**

1. Refresh tool cache: `POST /configurations/{id}/refresh`
2. Check MCP server is responding
3. Verify server implements `/mcp/tools` endpoint
4. Check server logs for errors


## Next Steps

- [Use connectors with AI assistants](/docs/documentation/personal-connectors/use-personal-connector)
- [Monitor usage and costs](/docs/documentation/core-concepts/synapses-and-neurons)
- [API Reference](/docs/api-reference/personal-connectors/configurations/create)