Add mcp_connector() for provider-hosted MCP server connections

[gadenbuie]

Closes #985 (supersedes).

Summary

• Adds mcp_connector(), a user-facing API for connecting to remote MCP servers via the provider's API. Both Anthropic and OpenAI are supported. Connectors are registered with $register_tool() and the provider handles tool discovery and execution server-side.
• Adds ContentMcpToolRequest, ContentMcpToolResult, and ContentMcpListTools content classes that inherit from existing tool content types, so MCP tool calls integrate naturally with conversation display, echo, and streaming.
• MCP tool results are echoed during chat() and yielded during streaming when yield_as_content = TRUE.
• Refactors tool result formatting so that echoing tool requests/results during chat() and printing a Chat object use a consistent display style. Remote MCP servers like DeepWiki can return very large responses (17k+ lines), so tool results are now truncated in both echo output and conversation history, and long tool IDs are shortened for readability. The new formatting arguments flow from high-level methods and are prefixed with tool_ to avoid collisions.

Examples

Anthropic

chat <- chat_anthropic()
chat$register_tool(
  mcp_connector("https://mcp.deepwiki.com/mcp", name = "deepwiki")
)
chat$chat("Look up the tidyverse/ellmer repo with your deepwiki tools.")

OpenAI

chat <- chat_openai()
chat$register_tool(
  mcp_connector("https://mcp.deepwiki.com/mcp", name = "deepwiki")
)
chat$chat("Look up the tidyverse/ellmer repo with your deepwiki tools.")

Manual configuration without mcp_connector()

Anthropic

chat <- chat_anthropic(
  model = "claude-sonnet-4-5-20250929",
  beta_headers = "mcp-client-2025-11-20",
  api_args = list(
    mcp_servers = list(
      list(
        type = "url",
        url = "https://mcp.deepwiki.com/mcp",
        name = "deepwiki"
      )
    ),
    tools = list(
      list(
        type = "mcp_toolset",
        mcp_server_name = "deepwiki"
      )
    )
  )
)
chat$chat("Look up the tidyverse/ellmer repo with your deepwiki tools.")

OpenAI

chat <- chat_openai(
  model = "gpt-4.1",
  api_args = list(
    tools = list(
      list(
        type = "mcp",
        server_label = "deepwiki",
        server_url = "https://mcp.deepwiki.com/mcp",
        require_approval = "never"
      )
    )
  )
)
chat$chat("Look up the tidyverse/ellmer repo with your deepwiki tools.")

Documentation and resources

Anthropic

• MCP connector docs — remote MCP server integration guide
• Beta header required: mcp-client-2025-11-20
• Implemented:
  • MCP server config goes in a separate mcp_servers body field; tools use type: "mcp_toolset"
  • Tool calls appear as separate mcp_tool_use and mcp_tool_result content blocks
  • Result content blocks can contain text, image, and document types
  • Auth via authorization_token field on the server config entry
• Not implemented:
  • Tool filtering on mcp_toolset: default_config object with enabled and defer_loading booleans applied to all tools; configs named object with per-tool overrides keyed by tool name, each with its own enabled/defer_loading. Together these enable allow-listing (disable all by default, enable specific tools) or deny-listing individual tools.
  • cache_control on mcp_toolset: Prompt caching breakpoint on the toolset entry itself, similar to cache_control on other tool types.

OpenAI

• Remote MCP servers guide — MCP tool connector docs
• No beta header needed (production API)
• Implemented:
  • MCP config is inline as a type: "mcp" tool entry
  • Tool calls appear as merged mcp_call output blocks (request + result combined); tool discovery uses mcp_list_tools output blocks
  • require_approval support ("never" by default in ellmer); mcp_approval_request triggers an informative error
  • Auth via authorization field on the tool entry
• Not implemented:
  • Built-in OAuth connectors: Pre-built connectors identified by connector_id (e.g. connector_gmail, connector_google_drive, connector_dropbox) that use OAuth tokens instead of an arbitrary server URL. Our mcp_connector() only supports server_url.
  • Granular require_approval: Object form allowing per-tool approval control, e.g. {never: {tool_names: ["tool_a", "tool_b"]}}, so specific tools can bypass approval while others require it.
  • Interactive approval workflow: When require_approval is not "never", the API returns an mcp_approval_request output and expects an mcp_approval_response input in a follow-up request. We currently error instead of surfacing the approval request to the user.

[hadley]

Do you mind pointing me to the docs for context? I hadn't heard of these remote MCPs before.

[gadenbuie]

Do you mind pointing me to the docs for context? I hadn't heard of these remote MCPs before.

I just added a section to the PR description

[klin333]

i had to make an extra commit to https://github.com/klin333/ellmer/tree/feature/mcp-tool-content-types

it was needed to fix this crash:

x1 <- chat$chat("hello") # works
x2 <- chat$chat("Use Snowflake to list the databases visible to the MCP role.") # works
x3 <- chat$chat("hello") # crash
# Error in `req_perform_connection()` at ellmer/R/httr2.R:55:5:
# ! HTTP 400 Bad Request.
# ℹ messages.3.content.1.mcp_tool_use.input: Input should be an object [invalid_request_error]

[klin333]

hi all, any chance this can be merged soon?

[gadenbuie]

i had to make an extra commit to klin333/ellmer@feature/mcp-tool-content-types

@klin333 can you clarify: was the change you made related to this PR or to solve a separate issue? Can you also please include a complete reproducible example?

[klin333]

Hi @gadenbuie, thank you for looking into this.

While on commit 47cd0b9:

devtools::load_all()

snowflake_mcp_url <- "xxx"
access_token <- "yyy"

chat <- ellmer::chat_anthropic(
  model = "claude-sonnet-4-6",
  echo = "all",
  system_prompt = "You are a careful Snowflake data assistant."
)

chat$register_tool(
  ellmer::mcp_connector(
    url = snowflake_mcp_url,
    name = "snowflake",
    credentials = function() access_token
  )
)

x1 <- chat$chat("hello") # works
x2 <- chat$chat("Use Snowflake to list the databases visible to the current role.") # works
x3 <- chat$chat("hello") # crash
# Error in `req_perform_connection()` at ellmer/R/httr2.R:55:5:
# ! HTTP 400 Bad Request.
# ℹ messages.3.content.1.mcp_tool_use.input: Input should be an object [invalid_request_error]
# Run `rlang::last_trace()` to see where the error occurred.

> sessionInfo()
R version 4.5.2 (2025-10-31 ucrt)
Platform: x86_64-w64-mingw32/x64
Running under: Windows 11 x64 (build 26200)

Matrix products: default
  LAPACK version 3.12.1

locale:
[1] LC_COLLATE=English_Australia.utf8  LC_CTYPE=English_Australia.utf8    LC_MONETARY=English_Australia.utf8
[4] LC_NUMERIC=C                       LC_TIME=English_Australia.utf8    

time zone: Australia/Sydney
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] ellmer_0.4.1.9000 testthat_3.3.2   

loaded via a namespace (and not attached):
 [1] vctrs_0.6.5       cli_3.6.5         rlang_1.1.6       otel_0.2.0        purrr_1.1.0       pkgload_1.4.1     promises_1.5.0   
 [8] S7_0.2.1          coro_1.1.0        jsonlite_2.0.0    glue_1.8.0        rprojroot_2.1.1   pkgbuild_1.4.8    brio_1.1.5       
[15] rappdirs_0.3.3    tibble_3.3.0      ellipsis_0.3.2    fastmap_1.2.0     lifecycle_1.0.4   httr2_1.2.2       memoise_2.0.1    
[22] compiler_4.5.2    fs_1.6.6          sessioninfo_1.2.3 pkgconfig_2.0.3   Rcpp_1.1.1        rstudioapi_0.17.1 later_1.4.5      
[29] R6_2.6.1          curl_7.0.0        pillar_1.11.1     usethis_3.2.1     magrittr_2.0.4    withr_3.0.2       tools_4.5.2      
[36] devtools_2.4.6    remotes_2.5.0     cachem_1.1.0      desc_1.4.3    

When on commit 983f025, the above no longer crashes

[gadenbuie]

Thanks for the detailed reprex and for tracking down the root cause @klin333. I've updated the PR to reparse the input and to fix a similar bug in the OpenAI implementation.

Note that for now, I'm not taking the extra_args$tools merging fix. It's not directly needed to fix the problem with follow-up message after an MCP tool use round. Providing tool definitions through extra_args is very much an edge case and I think it's reasonable for ellmer to require users to commit to manual definitions if opting out of the typical $register_tool() workflow. But we can revisit that if you have a concrete use case where you need both approaches to coexist (in a new issue, please).