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

# Overview

> Connect your agents to external data through MCP servers, REST APIs, and local filesystems

Sources are the data connections that power your agents. They let your agent access external services, APIs, and files to complete tasks that require real-world data.

<Note>
  **Working on local files?** For direct filesystem access in a single directory, use the [Working Directory](/core-concepts/working-directory) instead. It provides built-in tools like `Read`, `Write`, and `Bash` without MCP configuration. Sources are best for external services or accessing multiple file locations.
</Note>

<Tip>
  **Just ask your agent.** The easiest way to add sources is to tell your agent what you need:

  * "Connect my GitHub account"
  * "Add Slack to this workspace"
  * "Set up access to my Obsidian vault"

  The agent handles configuration, authentication, and validation automatically.
</Tip>

## What Are Sources?

A source is any external data connection your agent can use:

* **MCP servers** - Standardized AI tool integrations
* **REST APIs** - Any service with HTTP endpoints
* **Local folders** - Bookmarks to folders on your machine

Each source gives your agent tools it can call during conversations. When you ask your agent to "check my GitHub issues" or "search the web," it's using sources behind the scenes. All source types — MCP servers, APIs, and local folders — work with every configured LLM provider, including Anthropic, OpenAI/Codex, Google Gemini, GitHub Copilot, and custom endpoints.

## Source Types

<CardGroup cols={3}>
  <Card title="MCP Servers" icon="plug" href="/sources/mcp-servers/overview">
    Model Context Protocol servers provide rich, pre-built tool integrations. Many services offer official MCP support.

    **Examples:** Linear, GitHub, Brave Search
  </Card>

  <Card title="REST APIs" icon="code" href="/sources/apis/overview">
    Connect to any service with an API. Provide documentation and your agent can make authenticated requests.

    **Examples:** Exa Search, custom backends
  </Card>

  <Card title="Local Folders" icon="bookmark" href="/sources/local-filesystems">
    Bookmark folders on your machine with documentation and quick access.

    **Examples:** Notes, downloads, reference directories
  </Card>
</CardGroup>

## How Sources Work

Each source lives in a folder at:

```
~/.craft-agent/workspaces/{workspace-id}/sources/{source-slug}/
```

A source folder contains:

* **`config.json`** - Connection settings, authentication type, status (required)
* **`guide.md`** - Instructions for your agent on how to use this source (optional)
* **`permissions.json`** - Custom rules for Explore mode (optional)
* **`icon.*`** - Visual icon for the source (optional)

### config.json

The configuration file defines how to connect to the source:

```json theme={null}
{
  "type": "mcp",
  "name": "Linear",
  "slug": "linear",
  "enabled": true,
  "provider": "linear",
  "mcp": {
    "url": "https://mcp.linear.app",
    "authType": "oauth"
  },
  "isAuthenticated": true,
  "connectionStatus": "connected"
}
```

Key fields:

* **`type`** - Source type: `mcp`, `api`, or `local`
* **`enabled`** - Whether the source is active
* **`provider`** - Service identifier (e.g., `"linear"`, `"github"`, `"custom"`)
* **`isAuthenticated`** - Whether credentials are stored
* **`connectionStatus`** - Current state: `connected`, `needs_auth`, `failed`, `untested`, or `local_disabled`

### icon.\*

Place an icon file in the source folder (`icon.svg`, `icon.png`) for custom branding. Icons are auto-discovered—no configuration needed.

**How icons work:**

| `config.icon` value         | Behavior                                                    |
| --------------------------- | ----------------------------------------------------------- |
| Emoji (`"🔧"`)              | Rendered as emoji                                           |
| Local path (`"./icon.svg"`) | Loads from source folder                                    |
| URL (`"https://..."`)       | Auto-downloaded by validation                               |
| Not set                     | Auto-discovers `icon.svg`/`icon.png`, falls back to favicon |

**Best practice:** Set `icon` to a URL when creating sources, then run validation. The icon is downloaded and cached locally for fast, offline display.

### guide.md

The guide file helps your agent understand how to use the source effectively:

```markdown theme={null}
# Linear

Issue and project tracking for the iOS team.

## Scope

Access to the "Craft iOS" project and related issues.

## Guidelines

- Search issues before creating duplicates
- Use labels consistently with team conventions
- Check sprint assignments before moving issues
```

<Tip>
  A well-written guide.md makes your agent significantly more effective. Include specific project names, team conventions, and common workflows.
</Tip>

## Activation and Deactivation

Sources can be enabled or disabled without removing them:

1. **In the UI**: Toggle the source on/off in the workspace settings
2. **In config.json**: Set `"enabled": false`

Disabled sources remain configured but won't be available to your agent during conversations.

## Source Lifecycle

1. **Setup** - Create source folder and config.json
2. **Authentication** - Store credentials (OAuth, API key, etc.)
3. **Testing** - Validate connection works
4. **Active use** - Source available in conversations
5. **Deactivation** - Disable when not needed

## Explore Mode Permissions

By default, sources work in Explore mode with read-only access. Create a `permissions.json` to define which operations are safe:

```json theme={null}
{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "All list operations" },
    { "pattern": "get", "comment": "All read operations" },
    { "pattern": "search", "comment": "All search operations" }
  ]
}
```

Patterns are automatically scoped to the source, so `list` becomes `mcp__linear__.*list` internally.

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Servers" icon="plug" href="/sources/mcp-servers/overview">
    Connect to services with MCP support
  </Card>

  <Card title="REST APIs" icon="code" href="/sources/apis/overview">
    Connect to any service with an API
  </Card>

  <Card title="Local Folders" icon="bookmark" href="/sources/local-filesystems">
    Bookmark folders on your machine
  </Card>

  <Card title="Authentication" icon="key" href="/sources/mcp-servers/authentication">
    Set up secure credentials
  </Card>
</CardGroup>