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

> Configure and manage MCP servers

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

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

<Tabs>
  <Tab title="Client">
    ## Add Servers Through Your AI Client

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

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

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

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

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

    <Warning>
      Make sure your client installs the **official** MCP server for each service — not a random community fork. Look for servers 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 client to confirm the publisher before installing.
    </Warning>

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

    ## Popular Servers

    Select a server to see setup instructions.

    <AccordionGroup>
      <Accordion title="Notion">
        Ask your AI client: *"Add the Notion MCP server"*

        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 AI client: *"Add the Slack MCP server"*

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

      <Accordion title="Linear">
        Ask your AI client: *"Add the Linear MCP server"*

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

      <Accordion title="GitHub">
        Ask your AI client: *"Add the GitHub MCP server"*

        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 AI client: *"Add the Figma MCP server"*

        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 AI client: *"Add the AWS MCP server"*

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

      <Accordion title="Jira">
        Ask your AI client: *"Add the Jira MCP server"*

        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 AI client: *"Add the Mintlify MCP server"*

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

      <Accordion title="Salesforce">
        Ask your AI client: *"Add the Salesforce MCP server"*

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

      <Accordion title="Datadog">
        Ask your AI client: *"Add the Datadog MCP server"*

        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 AI client: *"Add the PostgreSQL MCP server"*

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

      <Accordion title="Vanta">
        Ask your AI client: *"Add the Vanta MCP server"*

        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 AI client: *"Add the filesystem server for my project files"*

        The filesystem server 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 client. Never point it at your home directory or root.
      </Accordion>
    </AccordionGroup>

    ## Supported Clients

    Ultra works with all major MCP-compatible AI clients:

    | Client                 | 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 clients are detected on your machine, or `ultra install` to configure a specific client.
  </Tab>

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

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

    ```bash theme={null}
    # Search for servers
    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 Servers by URL

    Add HTTP-based MCP servers directly by URL:

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

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

    Ultra auto-detects transport type and authentication requirements. If the server 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 Servers

    Select a server 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 AI client 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 AI client 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 server 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 server 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 client. Never point it at your home directory or root.
      </Accordion>
    </AccordionGroup>

    ## Adding Servers Manually

    Use `ultra servers add` for full control:

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

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

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

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

    ## Managing Servers

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

    # Enable/disable
    ultra servers enable filesystem
    ultra servers disable filesystem

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

    ## Stdio vs HTTP Transport

    ### Stdio Transport

    For servers 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 servers. 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 servers:

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

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

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

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

    ### OAuth2

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

    ### Environment Variables

    For stdio servers, 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>