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

# Upstream Connectors

> Configure and manage MCP connectors

Ultra proxies requests to one or more upstream MCP connectors. Connectors can use **stdio** transport (local commands) or **HTTP** transport (remote URLs).

<Warning>
  Only add MCP connectors from official or trusted sources. Untrusted community connectors can execute arbitrary code on your machine (stdio transport) or receive sensitive data from your AI agents (HTTP transport). Stick to connectors from the [official MCP Registry](https://github.com/modelcontextprotocol/servers), verified publishers, or connectors your organization has reviewed and approved.
</Warning>

<Tabs>
  <Tab title="Agent">
    ## Add Connectors Through Your Agent

    The simplest way to add MCP connectors is to ask your agent to do it for you. Since Ultra is already connected to your agent, just tell it what services you want to connect:

    * *"Connect to the Notion connector"*
    * *"Add the GitHub connector"*
    * *"Set up the filesystem connector so you can read my project files"*
    * *"Add the Linear connector"*

    Your agent will work with Ultra to search the registry, install the connector, and configure any required authentication (API keys, OAuth, etc.).

    <Tip>
      In agents that support MCP Apps, you can view, discover, add, and reconnect connectors from an interactive panel — see the [ultra\_servers MCP App](/getting-started/mcp-app).
    </Tip>

    Ultra hot-loads the new connector with no restart of its own. Most agents pick up the new tools automatically; if they don't appear, refresh or restart your agent.

    <Warning>
      Make sure your agent installs the **official** MCP connector for each service — not a random community fork. Look for connectors published by the service provider (e.g., `@notionhq/notion-mcp-server`) or from the [official MCP Registry](https://github.com/modelcontextprotocol/servers). If you're unsure, ask your agent to confirm the publisher before installing.
    </Warning>

    <Tip>
      You can also ask your agent to list your current connectors (*"What connectors do I have connected?"*) or remove ones you no longer need.
    </Tip>

    ## Popular Connectors

    Select a connector to see setup instructions.

    <AccordionGroup>
      <Accordion title="Notion">
        Ask your agent: *"Add the Notion connector"*

        Notion uses **OAuth**. You will be redirected to Notion in your browser to authorize access to your workspace. Tokens are stored and refreshed automatically.

        You need to be a member of the Notion workspace you want to connect.
      </Accordion>

      <Accordion title="Slack">
        Ask your agent: *"Add the Slack connector"*

        Slack uses **OAuth**. You will be redirected to Slack in your browser to authorize.
      </Accordion>

      <Accordion title="Linear">
        Ask your agent: *"Add the Linear connector"*

        Linear uses **OAuth**. Authorize in your browser when prompted.
      </Accordion>

      <Accordion title="GitHub">
        Ask your agent: *"Add the GitHub connector"*

        You will be prompted for a **Personal Access Token (PAT)**. Create one at [github.com/settings/tokens](https://github.com/settings/tokens) with the scopes you need (typically `repo` and `read:org`).

        Use a **fine-grained PAT** scoped to only the repositories you need for better security.
      </Accordion>

      <Accordion title="Figma">
        Ask your agent: *"Add the Figma connector"*

        Figma uses **OAuth**. You will be redirected to Figma in your browser to authorize access to your files and projects.
      </Accordion>

      <Accordion title="AWS">
        Ask your agent: *"Add the AWS connector"*

        You will need AWS credentials configured on your machine (via `~/.aws/credentials` or environment variables).
      </Accordion>

      <Accordion title="Jira">
        Ask your agent: *"Add the Jira connector"*

        You will be prompted for your Jira instance URL and an **API token**. Create one at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
      </Accordion>

      <Accordion title="Mintlify">
        Ask your agent: *"Add the Mintlify connector"*

        You will need your Mintlify project subdomain or API key.
      </Accordion>

      <Accordion title="Salesforce">
        Ask your agent: *"Add the Salesforce connector"*

        Salesforce uses **OAuth**. You will be redirected to Salesforce in your browser to authorize access to your org.
      </Accordion>

      <Accordion title="Datadog">
        Ask your agent: *"Add the Datadog connector"*

        You will be prompted for your Datadog **API key** and **application key**. Find these in your Datadog org settings under API Keys.
      </Accordion>

      <Accordion title="PostgreSQL">
        Ask your agent: *"Add the PostgreSQL connector"*

        You will be prompted for your database connection string. Use a read-only database user when possible.
      </Accordion>

      <Accordion title="Vanta">
        Ask your agent: *"Add the Vanta connector"*

        Vanta uses **OAuth**. You will be redirected to Vanta in your browser to authorize. Once approved, the token is stored and refreshed automatically.

        You need an active Vanta account with appropriate permissions. If you see an authentication error, check with your Vanta admin that your account has API access enabled.
      </Accordion>

      <Accordion title="Filesystem">
        Ask your agent: *"Add the filesystem connector for my project files"*

        The filesystem connector runs locally and does not require authentication. You will be asked which directories to allow access to.

        Only grant access to directories you are comfortable sharing with your AI agent. Never point it at your home directory or root.
      </Accordion>
    </AccordionGroup>

    ## Supported Agents

    Ultra works with all major MCP-compatible AI agents:

    | Agent                  | Type                  |
    | ---------------------- | --------------------- |
    | **Claude Desktop**     | Desktop app           |
    | **Cursor**             | IDE                   |
    | **VS Code**            | IDE                   |
    | **GitHub Copilot**     | IDE (via VS Code)     |
    | **Claude Code**        | CLI                   |
    | **Codex**              | CLI                   |
    | **Windsurf**           | IDE                   |
    | **Roo Code**           | VS Code extension     |
    | **Goose**              | CLI                   |
    | **Gemini**             | Desktop app           |
    | **Antigravity**        | IDE / CLI             |
    | **LM Studio**          | Desktop app           |
    | **Amazon Q Developer** | CLI                   |
    | **Zed**                | IDE                   |
    | **Ona**                | Cloud dev environment |
    | **Hermes**             | Agent framework       |

    Run `ultra doctor` to see which agents are detected on your machine, or `ultra install` to configure a specific agent.
  </Tab>

  <Tab title="Terminal">
    ## Adding Connectors from Registry

    The easiest way to add connectors is from the MCP registry:

    ```bash theme={null}
    # Search for connectors
    ultra search filesystem

    # Add by name (searches registries)
    ultra add filesystem

    # Add by full package name
    ultra add @modelcontextprotocol/server-filesystem

    # Add with a custom name
    ultra add @modelcontextprotocol/server-filesystem --name myfiles
    ```

    When adding from the registry, Ultra automatically tests the connection, detects authentication requirements, and prompts for any required configuration (API keys, file paths, etc.).

    ## Adding Remote Connectors by URL

    Add HTTP-based MCP connectors directly by URL:

    ```bash theme={null}
    # Add a remote connector
    ultra add https://mcp.slack.com/mcp

    # With a custom name
    ultra add https://remote.example.com/mcp --name myconnector
    ```

    Ultra auto-detects transport type and authentication requirements. If the connector requires OAuth, you'll be prompted to authorize when it's first used. For token-based auth, Ultra prompts for the token during setup.

    ## Popular Connectors

    Select a connector below for specific setup instructions.

    <AccordionGroup>
      <Accordion title="Notion">
        ```bash theme={null}
        ultra add notion
        ```

        Notion uses **OAuth**. Ultra opens your browser for authorization. Tokens are stored and refreshed automatically.

        You need to be a member of the Notion workspace you want to connect.
      </Accordion>

      <Accordion title="Slack">
        ```bash theme={null}
        ultra add https://mcp.slack.com/mcp --name slack
        ```

        Slack uses **OAuth**. Ultra opens your browser to authorize. Once approved, your agent can send messages, search conversations, and interact with your workspace.
      </Accordion>

      <Accordion title="Linear">
        ```bash theme={null}
        ultra add linear
        ```

        Linear uses **OAuth**. Authorize in your browser when prompted. Your agent can then read and manage issues, projects, and cycles.
      </Accordion>

      <Accordion title="GitHub">
        ```bash theme={null}
        ultra add github
        ```

        GitHub requires a **Personal Access Token (PAT)**. Ultra prompts you to enter it during setup. Create one at [github.com/settings/tokens](https://github.com/settings/tokens) with the scopes you need (typically `repo` and `read:org`).

        Use a **fine-grained PAT** scoped to only the repositories you need for better security.
      </Accordion>

      <Accordion title="Figma">
        ```bash theme={null}
        ultra add https://mcp.figma.com/mcp --name figma
        ```

        Figma uses **OAuth**. Ultra opens your browser for authorization. Tokens are stored and refreshed automatically.
      </Accordion>

      <Accordion title="AWS">
        ```bash theme={null}
        ultra add aws
        ```

        The AWS connector uses your local AWS credentials (`~/.aws/credentials` or environment variables). Make sure `aws configure` is set up before adding.
      </Accordion>

      <Accordion title="Jira">
        ```bash theme={null}
        ultra add jira
        ```

        Jira requires your instance URL and an **API token**. Create one at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). Ultra prompts for both during setup.
      </Accordion>

      <Accordion title="Mintlify">
        ```bash theme={null}
        ultra add mintlify
        ```

        When prompted, enter your Mintlify project subdomain or API key.
      </Accordion>

      <Accordion title="Salesforce">
        ```bash theme={null}
        ultra add salesforce
        ```

        Salesforce uses **OAuth**. Ultra opens your browser for authorization. Tokens are stored and refreshed automatically.
      </Accordion>

      <Accordion title="Datadog">
        ```bash theme={null}
        ultra add datadog
        ```

        Datadog requires an **API key** and **application key**. Find these in your Datadog org settings under API Keys. Ultra prompts for both during setup.
      </Accordion>

      <Accordion title="PostgreSQL">
        ```bash theme={null}
        ultra add postgres
        ```

        When prompted, enter your PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/dbname`). Use a read-only database user when possible.
      </Accordion>

      <Accordion title="Vanta">
        ```bash theme={null}
        ultra add https://mcp.vanta.com/mcp --name vanta
        ```

        Vanta uses **OAuth**. Ultra detects this automatically and opens your browser to authorize. Once approved, tokens are stored and refreshed automatically.

        You need an active Vanta account with appropriate permissions. If you see an authentication error, check with your Vanta admin that your account has API access enabled.
      </Accordion>

      <Accordion title="Filesystem">
        ```bash theme={null}
        ultra add filesystem
        ```

        The filesystem connector runs locally (stdio transport) and does not require authentication. When prompted, specify the directory paths you want to allow access to.

        Only grant access to directories you are comfortable sharing with your AI agent. Never point it at your home directory or root.
      </Accordion>
    </AccordionGroup>

    ## Adding Connectors Manually

    Use `ultra connectors add` for full control:

    ```bash theme={null}
    # Stdio transport (local command)
    ultra connectors add filesystem \
      --command npx \
      --args "-y @modelcontextprotocol/server-filesystem /tmp"

    # HTTP transport (remote URL)
    ultra connectors add remote-api --url https://mcp.example.com/sse

    # With environment variables
    ultra connectors add github \
      --command npx \
      --args "-y @modelcontextprotocol/server-github" \
      --env "GITHUB_TOKEN=ghp_xxx"

    # Add in disabled state
    ultra connectors add test-connector --command ./test-server --disabled
    ```

    ## Managing Connectors

    ```bash theme={null}
    # List all connectors
    ultra connectors

    # Enable/disable
    ultra connectors enable filesystem
    ultra connectors disable filesystem

    # Remove
    ultra connectors remove filesystem
    ultra connectors remove filesystem --force  # Skip confirmation
    ```

    ## Stdio vs HTTP Transport

    ### Stdio Transport

    For connectors that run as local processes. Ultra spawns the process and communicates over stdin/stdout.

    ```yaml theme={null}
    upstream:
      filesystem:
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        env:
          NODE_ENV: production
        enabled: true
    ```

    ### HTTP Transport

    For remote connectors. Ultra connects over HTTP/SSE.

    ```yaml theme={null}
    upstream:
      notion:
        url: "https://mcp.notion.so"
        headers:
          Authorization: "Bearer secret_xxx"
        enabled: true
    ```

    ## Authentication

    ### Token-Based Auth

    Set auth tokens for HTTP connectors:

    ```bash theme={null}
    # Set during add (interactive)
    ultra add https://mcp.example.com/sse

    # Set after adding
    ultra config set-token my-connector YOUR_TOKEN

    # Set a custom header
    ultra config set-header my-connector X-API-Key YOUR_KEY
    ```

    Tokens are stored as `Authorization: Bearer {token}` headers in the config file.

    ### OAuth2

    Ultra supports OAuth2 authentication for upstream connectors that require it. The OAuth flow is handled automatically at runtime — when a connector requires authorization, Ultra opens a browser for you to complete the flow and stores the tokens for future requests.

    ### Environment Variables

    For stdio connectors, pass secrets via environment variables instead of hardcoding them in args:

    ```yaml theme={null}
    upstream:
      github:
        command: npx
        args: ["-y", "@modelcontextprotocol/server-github"]
        env:
          GITHUB_TOKEN: "ghp_xxxxxxxxxxxx"
        enabled: true
    ```
  </Tab>
</Tabs>