Setting Up an MCP Server

MCP servers give AI tools access to external data - your CRM, your codebase, your internal tools. But the setup process varies depending on the server type, the AI client you're using, and the authentication method.

This guide covers the general pattern for connecting any MCP server to any MCP client. We'll use Outrun's MCP server as a worked example throughout, but the concepts apply to any MCP server you encounter.

Two Transport Types

MCP servers communicate with AI clients over one of two transport types. Understanding which one your server uses determines how you configure it.

Local (stdio) Servers

The AI client spawns the MCP server as a child process on your machine. Communication happens over stdin/stdout. This is common for servers that wrap local tools - file systems, databases, CLI utilities.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

The client starts the process, sends JSON-RPC messages to its stdin, and reads responses from its stdout. No network involved.

Remote (Streamable HTTP) Servers

The MCP server runs on a remote host. The client connects over HTTPS and communicates via Streamable HTTP - a transport that supports both request-response and server-initiated events over a single HTTP connection.

{
  "mcpServers": {
    "my-saas-tool": {
      "url": "https://api.example.com/mcp"
    }
  }
}

Remote servers almost always require authentication. Most use OAuth 2.0, which the MCP protocol has built-in support for.

Configuring AI Clients

Each AI client stores MCP server configuration in a different location. The format is nearly identical across clients - the main difference is the file path.

Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "outrun": {
      "url": "https://api.outrun.dev/mcp"
    }
  }
}

Restart Claude Desktop after editing. The server appears in the MCP tools panel.

Claude Code

Create .mcp.json in your project root (or home directory for global access):

{
  "mcpServers": {
    "outrun": {
      "type": "url",
      "url": "https://api.outrun.dev/mcp"
    }
  }
}

Claude Code picks this up automatically - no restart needed.

Cursor

Cursor uses the same .mcp.json format. Create it in your project root:

{
  "mcpServers": {
    "outrun": {
      "url": "https://api.outrun.dev/mcp"
    }
  }
}

Multiple Servers

You can connect to multiple MCP servers simultaneously. Each gets a unique key:

{
  "mcpServers": {
    "outrun": {
      "url": "https://api.outrun.dev/mcp"
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "./docs"]
    }
  }
}

The AI model sees tools from all connected servers and can use them together in a single conversation.

OAuth Authentication

Remote MCP servers typically use OAuth 2.0. The MCP protocol standardises how this works so you don't need to configure tokens manually.

How It Works

When you first connect to a remote MCP server, the following happens automatically:

1. Client discovers the server's OAuth endpoints
   GET /.well-known/oauth-authorization-server

2. Client registers itself (if needed)
   POST /oauth/register

3. Client opens your browser for consent
   GET /oauth/authorize → you see a consent screen

4. You approve the requested permissions
   The server creates an authorization code

5. Client exchanges the code for a token
   POST /oauth/token → bearer token stored locally

6. All future requests use this token
   Authorization: Bearer <token>

You don't write any of this. The MCP client handles the entire flow. You just see a browser window asking you to approve access.

The Consent Screen

The consent screen shows you exactly what the MCP client is requesting access to. For example, when Claude Desktop connects to Outrun's MCP server:

• Which capabilities (tools) the client wants - querying data, managing workflows, running agents
• Which data sources it can see - all sources, or specific integrations you select
• Which object types it can access - people, organizations, activities, relationships

You choose what to grant. The resulting token is scoped to exactly those permissions - nothing more.

Scopes and Permissions

Scopes define what an MCP client can do with your data. Different servers have different scope systems, but the pattern is universal: the server defines the scopes, and you choose which to grant during consent.

Outrun's Scope System

Outrun uses three scope types:

Action scopes control which MCP tools are available:

Source scopes restrict which connected integrations are visible. If you grant source:hubspot-uuid but not source:salesforce-uuid, the client only sees HubSpot data.

Object type scopes restrict which data types are accessible: object:people, object:organizations, object:activities, object:relationships.

If you don't restrict sources or object types, the client sees everything in your workspace. This is fine for trusted tools - but for third-party integrations, narrowing the scope is good practice.

Available Tools (Outrun Example)

Once connected, the AI client sees the tools your scopes allow. Here's what Outrun's MCP server exposes:

Tools outside your granted scopes don't appear at all - the client never sees them.

Verify the Connection

After connecting, test by asking your AI tool something that requires MCP data:

How many people records are in my Outrun workspace?

If the connection is working, the AI tool calls the get-object-count tool via MCP and returns a live count from your workspace. If it fails, check:

1. Server URL - is the URL correct and reachable?
2. OAuth consent - did the browser window appear and did you approve?
3. Scopes - did you grant the scopes needed for the tools you're trying to use?
4. Network - can the client reach the server (firewalls, VPN, proxy)?

Security Best Practices

Principle of Least Privilege

Grant only the scopes each client needs. Your IDE assistant probably needs action:query to look up records, but doesn't need action:agents to create AI agents.

Review Connected Apps

Periodically review which MCP clients have access to your workspace. Revoke tokens for tools you no longer use.

Workspace Isolation

Each MCP token is scoped to one workspace. A client connected to your "Production" workspace cannot access your "Staging" workspace, even with the same user account.

Audit Trail

Every MCP operation is logged. Review access patterns if you see unexpected data queries or high request volumes.

What's Next

With MCP connected, your AI tools have live access to your workspace data. But what happens when a workflow doesn't behave as expected? The next guide covers workflow debugging - how to trace execution, identify failures, and fix issues using Outrun's built-in debugging tools.