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

# Overview

CORE integrations connect external services to provide activity sync and MCP tools for AI agents. This reference covers integration architecture and event types.

## Integration Capabilities

1. **Activity Sync** - Capture events into knowledge graph
2. **MCP Tools** - Expose service actions to AI agents (required)

## File Structure

* **index.ts** - Event router (SETUP, SYNC/PROCESS, GET\_TOOLS, CALL\_TOOL)
* **account-create.ts** - OAuth handler
* **schedule.ts** OR **create-activity.ts + identify.ts** - Activity sync
* **mcp/index.ts** - MCP tool definitions and implementations

## Integration Types

**Webhook-Based** - Real-time events (Slack, Discord)

* Events: SETUP, IDENTIFY, PROCESS, GET\_TOOLS, CALL\_TOOL
* Best for: Chat, real-time notifications

**Schedule-Based** - Periodic polling (GitHub, Linear)

* Events: SETUP, SYNC, GET\_TOOLS, CALL\_TOOL
* Best for: APIs without webhooks, batch processing
* Frequency: 5-15 minute cron schedule

## Spec Configuration

Returned by `getSpec()` in your CLI class:

```typescript theme={null}
{
  name: 'Service Name',
  key: 'service-key',
  description: 'Integration description',
  icon: 'icon-name',
  schedule: { frequency: '*/5 * * * *' },  // For schedule-based
  auth: {
    OAuth2: {
      token_url: 'https://api.service.com/oauth/token',
      authorization_url: 'https://api.service.com/oauth/authorize',
      scopes: ['read', 'write'],
      scope_separator: ',',
    }
  },
  mcp: { type: 'cli' }  // Always use 'cli' for custom tools
}
```

## Event Types

**All integrations handle:**

```typescript theme={null}
case IntegrationEventType.SETUP:
  return await integrationCreate(eventPayload.eventBody);

case IntegrationEventType.GET_TOOLS:
  return await getTools();

case IntegrationEventType.CALL_TOOL:
  const { name, arguments: args } = eventPayload.eventBody;
  return await callTool(name, args, eventPayload.config.apiKey);
```

**Schedule-based adds:**

```typescript theme={null}
case IntegrationEventType.SYNC:
  return await handleSchedule(eventPayload.config, eventPayload.state);
```

**Webhook-based adds:**

```typescript theme={null}
case IntegrationEventType.IDENTIFY:
  return [{ type: 'identifier', data: eventPayload.eventBody.event.user }];

case IntegrationEventType.PROCESS:
  return await createActivityEvent(eventPayload.eventBody.eventData, eventPayload.config);
```

## Return Types

**SETUP** - Account creation:

```typescript theme={null}
[{ type: 'account', data: { accountId, config, settings } }]
```

**SYNC** - Activity list + state:

```typescript theme={null}
[
  { type: 'activity', data: { text, sourceURL } },
  { type: 'state', data: { lastSyncTime, ...otherState } }
]
```

**PROCESS** - Activity list:

```typescript theme={null}
[{ type: 'activity', data: { text, sourceURL } }]
```

**IDENTIFY** - User identifier:

```typescript theme={null}
[{ type: 'identifier', data: 'user-id' }]
```

**GET\_TOOLS** - Tool list:

```typescript theme={null}
[{ name: 'create_issue', description: '...', inputSchema: {...} }]
```

**CALL\_TOOL** - Tool result:

```typescript theme={null}
{ content: [{ type: 'text', text: 'Result message' }] }
```

## MCP Tools

All integrations must implement custom MCP tools using `type: 'cli'`:

```typescript theme={null}
// src/mcp/index.ts
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

const CreateIssueSchema = z.object({
  title: z.string().describe('Issue title'),
  description: z.string().optional(),
});

export async function getTools() {
  return [{
    name: 'create_issue',
    description: 'Create a new issue',
    inputSchema: zodToJsonSchema(CreateIssueSchema),
  }];
}

export async function callTool(name: string, args: any, apiKey: string) {
  if (name === 'create_issue') {
    const result = await yourApiCall(apiKey, args);
    return { content: [{ type: 'text', text: `Created #${result.id}` }] };
  }
  throw new Error(`Unknown tool: ${name}`);
}
```

## Best Practices

**Activity Messages:**

* Be descriptive with context
* Always include sourceURL
* Filter noise (only relevant events)

**State Management:**

* Save lastSyncTime after each sync
* Default to 24 hours on first sync
* Use pagination for large datasets

**Error Handling:**

* Return empty arrays on errors (don't throw)
* Continue processing if one item fails
* Validate tokens early

**MCP Tools:**

* Use clear descriptions
* Validate all inputs
* Return structured responses
* Handle rate limiting

## Reference Examples

* **Schedule-based**: [GitHub](/integrations/github), [Linear](/integrations/linear)
* **Webhook-based**: [Slack](/integrations/slack), [Discord](/integrations/discord)
* **Detailed guides**: [Schedule-Based Guide](/integrations/schedule-based-guide), [Webhook-Based Guide](/integrations/webhook-based-guide)

## Contributing

Want to build an integration? See our [step-by-step contributor guide](/opensource/building-integrations).