Overview

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

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.

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

MCP Servers

Model Context Protocol servers provide rich, pre-built tool integrations. Many services offer official MCP support.

Examples: Linear, GitHub, Brave Search

REST APIs

Connect to any service with an API. Provide documentation and your agent can make authenticated requests.

Examples: Exa Search, custom backends

Local Folders

Bookmark folders on your machine with documentation and quick access.

Examples: Notes, downloads, reference directories

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:

{
  "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:

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

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:

{
  "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

MCP Servers

Connect to services with MCP support

REST APIs

Connect to any service with an API

Local Folders

Bookmark folders on your machine

Authentication

Set up secure credentials