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

# Sources

> Connect Synti's agent to external tools, services, and folders through MCP servers, REST APIs, and local filesystems.

Sources are how you give Synti's agent access to the world beyond a single conversation. A source is a named, reusable connection—an integration you configure once and the agent can draw on whenever a task needs it. Because Synti is local-first, every source lives on your machine, and the agent only ever reaches a service you have explicitly connected.

There are three kinds of sources, each suited to a different way of reaching data:

<CardGroup cols={3}>
  <Card title="MCP Servers" icon="plug" href="/sources/mcp-servers/overview">
    Standardized tool integrations that expose ready-made capabilities—Linear, GitHub, search providers, databases, and more.
  </Card>

  <Card title="REST APIs" icon="globe" href="/sources/apis/overview">
    Any HTTP service. Point Synti at a base URL and auth method, and the agent can call its endpoints directly.
  </Card>

  <Card title="Local Filesystems" icon="folder" href="/sources/local-filesystems">
    Bookmark folders on your machine—notes, downloads, reference material—for quick, repeated access.
  </Card>
</CardGroup>

## Choosing a source kind

Each kind trades off convenience against flexibility.

| Kind             | Best for                                     | Tools the agent gets                        |
| ---------------- | -------------------------------------------- | ------------------------------------------- |
| MCP server       | Rich, pre-built integrations with a service  | Predefined tools published by the server    |
| REST API         | Any HTTP endpoint, including custom backends | A flexible HTTP tool that can call any path |
| Local filesystem | Referencing folders you return to often      | Read-oriented file tools (Read, Glob, Grep) |

<Tip>
  If you only need the agent to work inside one project directory, set a [Working Directory](/core-concepts/working-directory) instead of a filesystem source. Sources are best when you manage several external services or multiple folders at once.
</Tip>

## How sources are stored

Sources belong to a [workspace](/go-further/workspaces), so different workspaces can connect different services without overlap. Each source is a folder under your Synti config directory:

```text theme={null}
~/.synti/workspaces/{workspace-id}/sources/{source-slug}/
├── config.json        # connection settings, type, auth method, status (required)
├── guide.md           # notes for the agent on how to use this source (optional)
├── permissions.json   # custom Explore-mode rules for this source (optional)
└── icon.png           # cached icon for the sources list (optional)
```

### config.json

`config.json` is the only required file. Its shape depends on the source kind, but a few fields are common to all:

| Field              | Purpose                                                              |
| ------------------ | -------------------------------------------------------------------- |
| `type`             | `"mcp"`, `"api"`, or `"local"`                                       |
| `name`             | Display name shown in the sources list                               |
| `slug`             | URL-safe identifier (matches the folder name)                        |
| `enabled`          | Whether the source is active                                         |
| `provider`         | Service identifier (e.g. `github`, `local`)                          |
| `isAuthenticated`  | Whether valid credentials are stored                                 |
| `connectionStatus` | `connected`, `needs_auth`, `failed`, `untested`, or `local_disabled` |

Credentials are never written into `config.json`. They are encrypted separately—see [MCP authentication](/sources/mcp-servers/authentication) for how Synti stores and scopes secrets.

### Icons

Set `icon` to an emoji, a local file path, or a URL. When you provide a URL, Synti downloads the image and caches it locally so the sources list renders quickly and works offline.

## Permissions

By default, a source runs in read-only Explore mode: the agent can inspect and query, but actions that change state require your approval through [Permissions](/core-concepts/permissions). To broaden or narrow what a source may do, add a `permissions.json` file. Its patterns are automatically scoped to that source, so a rule you write for one integration never loosens access to another.

## The lifecycle of a source

<Steps>
  <Step title="Set up">
    Create the source folder and `config.json`, or just ask the agent to add it—Synti writes the configuration for you.
  </Step>

  <Step title="Authenticate">
    Provide credentials if the service needs them. Secrets are encrypted on disk, not stored in config.
  </Step>

  <Step title="Test">
    Synti validates connectivity and credentials so you know the source works before relying on it.
  </Step>

  <Step title="Use">
    The agent picks up the source's tools and uses them naturally as tasks require.
  </Step>

  <Step title="Deactivate">
    Toggle `enabled` off (in the UI or `config.json`) to pause a source without deleting it.
  </Step>
</Steps>

<Note>
  You rarely need to edit files by hand. Ask the agent to "connect the GitHub MCP server" or "add my Downloads folder as a source," and it handles configuration, authentication, and validation for you.
</Note>