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

# MCP Integration Overview

> Connect your AI agents to external services with Model Context Protocol - an open standard for AI integration

## What is MCP?

**MCP (Model Context Protocol)** is an open standard protocol that allows AI agents to securely connect to external tools and services. Think of it as a **universal adapter** that lets your agents interact with platforms like GitHub, Firecrawl, and custom services.

### Why Use MCP?

<CardGroup cols={2}>
  <Card title="Unified Integration" icon="plug">
    One protocol to connect to multiple platforms - no custom code for each service
  </Card>

  <Card title="Secure Authentication" icon="shield-check">
    Encrypted credentials with user/organization-level isolation
  </Card>

  <Card title="No-Code Setup" icon="wand-magic-sparkles">
    Configure integrations through the Admin UI - zero programming required
  </Card>

  <Card title="Real-Time Communication" icon="bolt">
    Agents can call external APIs and get responses in milliseconds
  </Card>
</CardGroup>

***

## How MCP Works in Junis

```mermaid theme={null}
graph LR
    A[User Message] --> B[Junis Agent]
    B --> C{MCP Platform}
    C -->|GitHub| D[GitHub API]
    C -->|Firecrawl| E[Firecrawl API]
    C -->|Custom| F[Custom Service]
    D --> H[Agent Response]
    E --> H
    F --> H
```

**Flow**:

1. User sends a message to your agent
2. Agent identifies the need for external data (e.g., "list GitHub issues")
3. Agent calls the appropriate MCP tool (e.g., `github_list_issues`)
4. MCP protocol handles authentication and API communication
5. External service returns data
6. Agent processes the data and responds to the user

***

## Supported Integrations

Junis supports a wide range of MCP integrations:

<CardGroup cols={2}>
  <Card title="Junis Magic" icon="wand-magic-sparkles">
    Full platform management — build agent teams, manage configurations, and control your organization from any MCP client. [Learn more](/guides/junis-magic)
  </Card>

  <Card title="GitHub" icon="github">
    Repository management, issues, PRs, and commits
  </Card>

  <Card title="Firecrawl" icon="spider">
    Web scraping and crawling
  </Card>

  <Card title="Composio (200+ Apps)" icon="key">
    OAuth integrations for Gmail, Slack, Jira, Salesforce, and more via [Composio](/integrations/composio)
  </Card>
</CardGroup>

### Desktop Agent (npx junis)

Connect your local device to the Junis platform with [`npx junis`](/guides/npx-junis). Agents can control files, execute commands, and automate browsers on your machine.

### Custom MCP Servers

You can also connect **custom MCP servers** to integrate any service that provides an MCP implementation. See the [Custom MCP guide](/guides/mcp/custom) for details.

<Info>
  **Need another platform?** MCP is an open standard - you can integrate any service that provides an MCP server. Check the [MCP Protocol website](https://modelcontextprotocol.io/) for community-contributed servers.
</Info>

***

## Authentication Priority System

Junis supports **three levels of authentication** for MCP platforms, with a clear priority order:

```
👤 User-Level > 🏢 Organization-Level > 🌍 System-Level
```

### User-Level (Highest Priority)

**Your personal credentials** for platforms like personal GitHub accounts.

**Use Case**: Individual authentication (e.g., accessing your personal GitHub repositories)

**Setup**: User Settings > MCP Credentials

**Example**:

* You set your personal GitHub token
* When agents query repositories, they use **your** GitHub account
* Other team members cannot access your GitHub credentials

### Organization-Level (Medium Priority)

**Team-shared credentials** for platforms like company GitHub or Firecrawl accounts.

**Use Case**: Shared team resources (e.g., querying company GitHub repositories)

**Setup**: Admin > MCP > Organization Credentials (Admin only)

**Example**:

* Admin sets the company GitHub PAT (Personal Access Token)
* All team members can query company repositories
* Each user doesn't need their own GitHub token

### System-Level (Lowest Priority)

**Global default credentials** provided by Junis for public integrations.

**Use Case**: Trial/demo purposes or when no user/org credentials exist

**Setup**: Automatically configured by Junis Super Admins

**Example**:

* Junis provides a default Firecrawl API key for testing
* Users can override with their own keys for production use

***

## MCP Types: Remote vs Local

MCP servers can be deployed in two ways:

<Tabs>
  <Tab title="Remote MCP">
    ### Remote MCP (HTTP/SSE)

    **How it works**: Your agent connects to an external MCP server via HTTP or Server-Sent Events (SSE).

    **Characteristics**:

    * No package installation required
    * Server runs independently (cloud-hosted)
    * Authentication via HTTP headers
    * Always-on availability

    **Examples**:

    * **GitHub MCP**: [https://api.githubcopilot.com/mcp/](https://api.githubcopilot.com/mcp/)
    * **Firecrawl MCP**: Firecrawl API endpoint
    * **Custom APIs**: Your company's internal MCP server

    **Setup Complexity**: ⭐⭐ (Easy - just provide URL and API key)
  </Tab>

  <Tab title="Local MCP">
    ### Local MCP (Subprocess)

    **How it works**: A process (NPX, Python script) runs locally on the Junis server for each session.

    **Characteristics**:

    * Requires package installation (`requirements.txt`)
    * Process spawned per agent session
    * Authentication via environment variables
    * On-demand execution

    **Examples**:

    * **Python-based MCPs**: Custom Python package
    * **NPX-based MCPs**: `npx @some/mcp-server`
    * **Custom Scripts**: Your Python/Node.js MCP implementation

    **Setup Complexity**: ⭐⭐⭐⭐ (Moderate - requires deployment)
  </Tab>
</Tabs>

<Warning>
  **Deployment Required**: Local MCPs require adding the package to `requirements.txt` and redeploying the backend. Remote MCPs can be added instantly without deployment.
</Warning>

***

## Quick Start Guide

### Option 1: Connect a Remote MCP (5 minutes)

<Steps>
  <Step title="Navigate to MCP">
    Go to **Team > MCP** in the sidebar
  </Step>

  <Step title="Click Connect">
    Find the platform you want to connect (e.g., GitHub) and click **"Connect"**
  </Step>

  <Step title="Enter Credentials">
    Provide the required information:

    * **MCP Server URL**: (e.g., `https://api.githubcopilot.com/mcp/`)
    * **Transport Type**: SSE or HTTP (check platform docs)
    * **API Key/Token**: Your authentication credentials
  </Step>

  <Step title="Test Connection">
    Click **"Test"** to verify the connection works
  </Step>

  <Step title="Enable for Agent">
    Go to **Admin > Agents**, edit your agent, and check the platform in the **"MCP Platforms"** section
  </Step>
</Steps>

### Option 2: Use Pre-Configured Global Platform

Many popular platforms are **already configured** at the system level!

<Steps>
  <Step title="Browse Available Platforms">
    Go to **Team > MCP** - platforms with a globe icon (🌍) are pre-configured
  </Step>

  <Step title="Add Your Credentials">
    Click **"Add Auth"** and provide your personal or organization credentials
  </Step>

  <Step title="Enable for Agent">
    The agent can immediately start using the platform!
  </Step>
</Steps>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="GitHub MCP Setup" icon="github" href="/guides/mcp/github">
    Connect GitHub repos, issues, and PRs
  </Card>

  <Card title="Firecrawl MCP Setup" icon="spider" href="/guides/mcp/firecrawl">
    Web scraping and crawling
  </Card>

  <Card title="Custom MCP Servers" icon="cog" href="/guides/mcp/custom">
    Build and integrate your own MCP servers
  </Card>

  <Card title="Agent Orchestration" icon="diagram-project" href="/guides/orchestration/overview">
    Learn how to configure agents with MCP
  </Card>
</CardGroup>

***

## Key Concepts to Remember

<AccordionGroup>
  <Accordion title="MCP Platform vs MCP Credentials" icon="key">
    * **MCP Platform**: The service definition (name, URL, authentication method)
    * **MCP Credentials**: Your actual API keys/tokens for that platform

    **Example**: GitHub is a platform. Your GitHub Personal Access Token (PAT) is the credential.
  </Accordion>

  <Accordion title="Why Three Authentication Levels?" icon="users">
    **Flexibility and Security**:

    * **User-Level**: Personal accounts (personal GitHub repos)
    * **Organization-Level**: Shared resources (company GitHub, team Firecrawl)
    * **System-Level**: Fallback/demo purposes

    Your user credentials **always override** organization credentials for enhanced privacy.
  </Accordion>

  <Accordion title="Transport Type: SSE vs HTTP" icon="network">
    **Server-Sent Events (SSE)**:

    * One-way streaming from server to client
    * Better for real-time updates

    **Streamable HTTP**:

    * Request-response with streaming support
    * More reliable for most APIs

    **Important**: Check the platform's documentation! Using the wrong type causes errors.
  </Accordion>

  <Accordion title="Can I create my own MCP server?" icon="code">
    **Yes!** MCP is an open protocol. You can:

    1. Build an MCP server for your internal APIs
    2. Host it on your infrastructure
    3. Add it to Junis as a Remote MCP
    4. Your agents can now access your custom services

    See the [MCP Protocol Spec](https://modelcontextprotocol.io/docs) for implementation details.
  </Accordion>
</AccordionGroup>

***

## Common Use Cases

### Development Automation Agent

**Platforms**: GitHub

* Monitor GitHub issues and PRs
* Automate code reviews
* Manage repository workflows

### Research & Analysis Agent

**Platforms**: Firecrawl, Custom MCP

* Scrape competitor websites with Firecrawl
* Extract and analyze web content
* Integrate with custom data processing services

### Content Discovery Agent

**Platforms**: Firecrawl, GitHub

* Crawl documentation sites
* Index technical resources
* Track industry trends

***

## Security & Best Practices

<Check>
  **✅ DO**:

  * Use **user-level** credentials for personal accounts (private GitHub)
  * Use **organization-level** credentials for shared team resources
  * Rotate API keys regularly (every 90 days recommended)
  * Test connections before deploying to production
  * Review MCP platform permissions (grant least privilege)
</Check>

<Warning>
  **❌ DON'T**:

  * Share personal API keys with team members (use org-level instead)
  * Store credentials in code or logs (Junis encrypts them automatically)
  * Grant excessive permissions (only enable what agents need)
  * Use production databases for testing (use test environments)
</Warning>

***

## Troubleshooting Quick Reference

| Issue                  | Possible Cause                     | Solution                                   |
| ---------------------- | ---------------------------------- | ------------------------------------------ |
| 405 Method Not Allowed | Wrong transport type (SSE vs HTTP) | Check platform docs, update transport type |
| 401 Unauthorized       | Invalid/expired API key            | Generate new API key, update credentials   |
| 403 Forbidden          | Insufficient permissions           | Check API key scopes/permissions           |
| Tools not loading      | Agent not connected to platform    | Edit agent, enable MCP platform            |
| Connection timeout     | MCP server down or unreachable     | Test connection, check server status       |

<Info>
  For detailed troubleshooting guides, see each platform's specific documentation page.
</Info>

***

## Platform-Specific Guides

<CardGroup cols={2}>
  <Card title="Junis Magic" href="/guides/junis-magic">
    Full platform management from any MCP client
  </Card>

  <Card title="GitHub" href="/guides/mcp/github">
    Repository management, issues, and PRs
  </Card>

  <Card title="Firecrawl" href="/guides/mcp/firecrawl">
    Web scraping and crawling
  </Card>

  <Card title="Composio" href="/integrations/composio">
    200+ OAuth app integrations
  </Card>

  <Card title="Desktop Agent" href="/guides/npx-junis">
    Device control with npx junis
  </Card>

  <Card title="Custom MCP" href="/guides/mcp/custom">
    Build your own MCP server
  </Card>
</CardGroup>

***

## FAQs

<AccordionGroup>
  <Accordion title="How many platforms can one agent use?">
    **Unlimited!** An agent can connect to as many MCP platforms as needed. For example, a research agent might use Firecrawl (web scraping) + GitHub (code analysis) + Custom MCP (data storage) simultaneously.
  </Accordion>

  <Accordion title="Do I need to pay for each platform separately?">
    **It depends**. MCP is just the connection protocol. You need active accounts/subscriptions for each service:

    * **Free**: GitHub (public repos)
    * **Paid**: Firecrawl (API credits), custom services
  </Accordion>

  <Accordion title="Can multiple agents share the same MCP connection?">
    **Yes!** Organization-level credentials are shared across all agents in your organization. The MCP Session Manager optimizes by reusing connections when possible.
  </Accordion>

  <Accordion title="What happens if my API key expires?">
    Agents will fail to connect and return authentication errors. Update the credentials in **Team > MCP** and the connection will resume immediately (no restart needed).
  </Accordion>

  <Accordion title="Can I use MCP in scheduled tasks?">
    **Absolutely!** Scheduled tasks can call agents with MCP integrations. Example: Daily report agent that scrapes data with Firecrawl and posts results to GitHub issues at 9 AM.
  </Accordion>
</AccordionGroup>

***

## Additional Resources

* **MCP Protocol Specification**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)
* **Community MCP Servers**: [https://github.com/topics/mcp-server](https://github.com/topics/mcp-server)
* **Junis API Documentation**: [Authentication & API Keys](/api-reference/authentication)
* **GitHub Discussions**: Share your MCP integrations!

<Note>
  **Need Help?** Contact us at [contact@junis.ai](mailto:contact@junis.ai) to ask questions about MCP integration and get expert support.
</Note>