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

# Custom Integrations (MCP)

> Connect your own MCP servers and tools so Gitar's rules and agents can use them

## Overview

Custom integrations let you extend Gitar with your own tools. Alongside the built-in integrations (Jira, Linear, Slack), you can register an [MCP](https://modelcontextprotocol.io) server — or a set of plain instructions — and Gitar's rules and agents can use it while reviewing pull requests and running automations.

<CardGroup cols={2}>
  <Card title="Any MCP Server" icon="plug">
    Connect any stdio or remote MCP server — internal search, ticketing, observability, or a service you built yourself
  </Card>

  <Card title="Instructions Only" icon="message">
    Skip the server and just give the agent guidance it should follow for a domain
  </Card>

  <Card title="Use in Rules" icon="scale-balanced">
    Grant a custom rule access by referencing the integration in its frontmatter
  </Card>

  <Card title="Org-Scoped Secrets" icon="key">
    API tokens and other secrets are stored per-organization and injected into the server at runtime
  </Card>
</CardGroup>

<Note>
  Custom integrations are an **Enterprise** feature. Contact your Gitar account team to have it enabled for your organization.
</Note>

## How It Works

Gitar connects to MCP servers over the Model Context Protocol. When an agent needs your tool, Gitar starts the server, injects any configured secrets and environment variables, and exposes the server's tools to the agent for that task. Secrets are resolved at runtime from your organization's secret store — they are never written into rule files or committed to your repository.

Two kinds of custom integration are supported:

* **MCP server** — Gitar runs the server and calls its tools. Use this for anything that reads or writes to an external system.
* **Instructions only** — no server; Gitar just adds your instructions to the agent when the integration is enabled. Useful for encoding domain conventions without a tool.

## Add a Custom Integration

<Steps>
  <Step title="Open the Integrations settings">
    In the Gitar dashboard, go to your organization's **Settings → Integrations** and click **Add Custom Integration**.
  </Step>

  <Step title="Describe the integration">
    Fill in the basic fields:

    | Field                  | Description                                                                                                                                                                            |
    | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Slug**               | Stable identifier used to reference the integration from rules. Lowercase letters, digits, and hyphens; 3–50 characters (for example `acme-search`). Cannot be changed after creation. |
    | **Name**               | Display name shown in the dashboard.                                                                                                                                                   |
    | **Short Description**  | One-line summary shown on the integration card.                                                                                                                                        |
    | **Long Description**   | Optional longer description.                                                                                                                                                           |
    | **Agent Instructions** | Optional guidance the agent follows whenever it uses this integration (for example, "Search internal docs before answering").                                                          |
  </Step>

  <Step title="Configure the MCP server">
    Under **MCP Server**, choose:

    * **None** — an instructions-only integration.
    * **Command** — Gitar runs the server as a subprocess. Enter the **Command** (for example `npx`) and space-separated **Arguments** (for example `-y @acme/acme-mcp-server`).

    <Note>
      To connect a **remote HTTP or SSE** MCP server, use the Command transport with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote): set the command to `npx` and the arguments to `-y mcp-remote https://mcp.example.com/sse`. Gitar bridges the remote server through this local command.
    </Note>
  </Step>

  <Step title="Create the integration">
    Click **Create**. The integration appears on your Integrations page and can be enabled or disabled at any time.
  </Step>

  <Step title="Add secrets and environment variables">
    If your server needs an API token or other configuration, add them on the **Configuration** page under the **Secrets** section after creating the integration. Gitar injects these into the server process when it runs. Store credentials as secrets — never in the command arguments.
  </Step>
</Steps>

## Using a Custom Integration in Rules

Once an integration is enabled, grant a [custom rule](/features/rules) access to it by listing its **slug** in the rule's `integrations` frontmatter — the same way you reference built-in integrations:

```markdown theme={null}
---
title: "Enrich PRs with Internal Docs"
description: "Look up internal documentation for changed modules"
when: "PRs that modify a documented internal service"
actions: "Comment with links to the relevant internal docs"
integrations: ["acme-search"]
---

# Internal Docs Enrichment

When a PR touches a documented service, use the Acme Search integration
to find the relevant internal docs and link them in a review comment.
```

When the rule runs, Gitar makes the integration's MCP tools available to the agent evaluating that rule. See [Repository Rules](/features/rules) for the full rule format.

## Managing Integrations

* **Enable / disable** — toggle an integration off to remove it from agents without deleting its configuration. Disabled integrations are never offered to agents.
* **Edit** — update the name, descriptions, instructions, or MCP command at any time from the integration card.
* **Delete** — remove the integration entirely. Deletion is always available, even if the Enterprise entitlement is later removed, so you can clean up configuration.

## Frequently Asked Questions

### What transports are supported?

Gitar runs MCP servers over stdio. Local servers run directly via the **Command** transport. Remote HTTP/SSE servers connect through the `mcp-remote` bridge described above.

### Where are my secrets stored?

Secrets are stored per-organization in Gitar's secret store and injected into the MCP server process at runtime. They are not written to rule files or your repository, and are not exposed to the model directly.

### Can I limit which tools a server exposes?

Yes. A server's tools can be restricted to an allow-list or filtered with a deny-list. Reach out to your Gitar account team if you need tool filtering configured for an integration.

### Who can create custom integrations?

Custom integrations require the Enterprise plan and are managed by organization administrators from **Settings → Integrations**.