MCP Servers

Posit Assistant can connect to external tool servers using the Model Context Protocol (MCP). This lets you extend the assistant with custom tools — database access, API integrations, internal services, and more.

Besides configuring servers yourself as described below, MCP servers can also come from a plugin you install from a marketplace. Plugin-provided servers are disabled until you approve them; see Plugins & Marketplaces for how that consent works.

Configuration

Add MCP servers to your settings file under the mcpServers key. Each server has a name and a configuration object.

You can configure MCP servers in both the global settings file (~/.posit/assistant/settings.json) and a project settings file (.posit/assistant/settings.json). The two are merged by server name — project entries override global entries with the same name, while global servers not mentioned in the project config remain available. To disable a global server for a specific project, add it to the project config with "enabled": false.

In older versions, these files were at ~/.positai/settings.json and .positai/settings.json.

Local Servers

Local servers run as subprocesses, communicating over stdio. Use these for MCP servers installed as npm packages, Python packages, or standalone executables.

{
	"mcpServers": {
		"filesystem": {
			"type": "local",
			"command": ["npx", "@anthropic-ai/mcp-server-filesystem", "/path/to/dir"]
		}
	}
}

Options

Key	Type	Description
`command`	`string[]`	Command and arguments to start the server. Required.
`environment`	`object`	Environment variables passed to the subprocess.
`enabled`	`boolean`	Whether this server is active. Default: `true`.
`timeout`	`number`	Connection timeout in milliseconds. Default: `10000`.

Environment Variables

Pass secrets to local servers via the environment field:

{
	"mcpServers": {
		"database": {
			"type": "local",
			"command": ["npx", "mcp-server-postgres"],
			"environment": {
				"DATABASE_URL": "{env:DATABASE_URL}"
			}
		}
	}
}

The {env:VAR_NAME} syntax expands to the value of the environment variable at runtime. This works in command, environment, url, and headers fields.

Remote Servers

Remote servers communicate over HTTP or SSE (Server-Sent Events).

{
	"mcpServers": {
		"my-api": {
			"type": "remote",
			"url": "https://mcp.example.com",
			"headers": {
				"Authorization": "Bearer {env:MCP_API_KEY}"
			}
		}
	}
}

Options

Key	Type	Description
`url`	`string`	Server URL. Required.
`headers`	`object`	HTTP headers for MCP transport and SDK-managed OAuth requests.
`transport`	`string`	Protocol: `"http"` (default) or `"sse"` (legacy).
`auth`	`object`	OAuth configuration (see below).
`enabled`	`boolean`	Whether this server is active. Default: `true`.
`timeout`	`number`	Connection timeout in milliseconds. Default: `10000`.

Authentication

Remote servers support three authentication approaches:

Configured headers other than User-Agent are sent to URLs on the MCP server’s origin. This includes OAuth endpoints when the authorization server shares that origin, as Posit Connect commonly does. They are not added to direct requests to a different-origin authorization server. A configured User-Agent replaces the assistant’s default on MCP transport requests and SDK-managed OAuth requests such as discovery, client registration, and token exchange, including when those requests use a different-origin authorization server. The interactive authorization page is opened in your browser and uses the browser’s own User-Agent. Because HTTP redirects are followed by the runtime, a redirecting endpoint may forward configured headers to its destination; configure the final MCP URL whenever possible to avoid that exposure.

Bearer Token

Pass a static token via headers:

{
	"headers": {
		"Authorization": "Bearer {env:API_TOKEN}"
	}
}

OAuth (Dynamic Registration)

Use "oauth" for servers that support RFC 7591 dynamic client registration:

{
	"auth": "oauth"
}

The assistant handles the browser-based authorization flow automatically.

OAuth (Pre-Registered Client)

For servers that require a specific client ID:

{
	"auth": {
		"clientId": "my-app",
		"clientSecret": "{env:CLIENT_SECRET}"
	}
}

Hosted on Posit Connect

Posit Connect can host MCP servers as published content. A Connect-hosted MCP server is a remote server whose URL is the content’s endpoint — MCP endpoints are conventionally mounted under a /mcp path (for example, https://connect.example.com/content/abc123/mcp).

Connect includes a built-in OAuth authorization server, so the recommended setup uses "auth": "oauth" — the assistant discovers Connect’s OAuth server and prompts you to authorize the connection in your browser:

{
	"mcpServers": {
		"connect-tools": {
			"type": "remote",
			"url": "https://connect.example.com/content/abc123/mcp",
			"auth": "oauth"
		}
	}
}

The OAuth authorization server requires Posit Connect 2026.02.0 or later. On older versions — or if your Connect administrator has disabled OAuth — authenticate with a Connect API key instead, passed as an Authorization: Key ... header:

{
	"mcpServers": {
		"connect-tools": {
			"type": "remote",
			"url": "https://connect.example.com/content/abc123/mcp",
			"headers": {
				"Authorization": "Key {env:CONNECT_API_KEY}"
			}
		}
	}
}

For more details, see the Posit Connect MCP servers documentation.

Signing in

A server configured with OAuth stays disconnected until you authorize it, and its authorization eventually expires. Rather than waiting for the next tool call to fail, you can sign in on demand from the session panel:

In the web, desktop, RStudio, and Positron apps, run /mcp (or /context, or click the token counter) to open the Session panel. Its MCP Servers section lists every configured server with its status, and a Sign in button on each one that needs authorizing.
In the terminal (TUI), run /mcp to open the Session window and go to its Activity tab. Servers needing sign-in are marked; move to one with the arrow keys and press Enter to start the browser flow.

Either way, the browser-based authorization flow opens, and the server connects and registers its tools once you approve it. This works the same for a server you configured yourself and one contributed by a plugin.

Enabling and Disabling

Set enabled: false to temporarily disable a server without removing its configuration:

{
	"mcpServers": {
		"staging-api": {
			"type": "remote",
			"url": "https://staging.example.com",
			"enabled": false
		}
	}
}

How It Works

When Posit Assistant starts, it connects to all enabled MCP servers and registers their tools. These tools appear alongside the built-in tools and can be used by the assistant in the same way — you don’t need to reference them explicitly.

Tools from MCP servers are namespaced: mcp__<server-name>__<tool-name>.