### Example HTTP GET Request with Authorization Header

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/authorization.md

An example of an HTTP GET request to an MCP server, demonstrating the inclusion of the Authorization header with a Bearer token.

```http
GET /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

--------------------------------

### Install mcptools from CRAN

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

Install the mcptools package from CRAN using the standard R installation command.

```r
install.packages("mcptools")
```

--------------------------------

### Install mcptools Development Version

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

Install the development version of the mcptools package using the pak package manager.

```r
pak::pak("posit-dev/mcptools")
```

--------------------------------

### Example Initialization Error Response

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/lifecycle.md

Illustrates a JSON-RPC error response indicating an unsupported protocol version during initialization. This is useful for diagnosing connection issues related to version compatibility.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2024-11-05"],
      "requested": "1.0.0"
    }
  }
}
```

--------------------------------

### MCP Protocol Version Header Example

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/transports.md

Specifies the MCP protocol version in HTTP requests using the MCP-Protocol-Version header.

```http
MCP-Protocol-Version: 2025-06-18
```

--------------------------------

### jsonrpc_response with Result and Error

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/utils.md

This example shows calling jsonrpc_response with both a result and an error, which triggers a warning. Use either 'result' or 'error', but not both.

```r
.res <- jsonrpc_response("789", result = "success", error = list(code = -32603,
  message = "error"))
```

--------------------------------

### jsonrpc_response with only ID

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/utils.md

This example shows calling jsonrpc_response with only a message ID. This also triggers a warning because neither 'result' nor 'error' is provided.

```r
.res <- jsonrpc_response("000")
```

--------------------------------

### Client Initialize Request

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/lifecycle.md

The client initiates the initialization phase by sending an 'initialize' request. This includes the protocol version, client capabilities, and client information.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### Setting up MCP Tools with ellmer

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

This R code demonstrates how to initialize ellmer's chat client and set the MCP tools obtained from mcptools. This allows Claude to interact with your R sessions.

```r
ch <- ellmer::chat_anthropic()
ch$set_tools(mcp_tools())

ch$chat("What issues are open on posit-dev/mcptools?")
```

--------------------------------

### Server Initialize Response

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/lifecycle.md

The server responds to the 'initialize' request with its own capabilities, server information, and optional instructions.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "title": "Example Server Display Name",
      "version": "1.0.0"
    },
    "instructions": "Optional instructions for the client"
  }
}
```

--------------------------------

### mcp_tools() Error: Non-existent File

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/client.md

Triggers an error when the specified configuration file does not exist. Ensure the `config` argument points to a valid file or that the default configuration file is present.

```R
mcp_tools("nonexistent/file/")
```

--------------------------------

### Complete MCP Authorization Flow with Dynamic Client Registration

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/authorization.md

This diagram illustrates the comprehensive authorization flow, including the optional dynamic client registration step.

```mermaid
sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
    Note over C: Extract resource_metadata URL from WWW-Authenticate

    C->>M: Request Protected Resource Metadata
    M->>C: Return metadata

    Note over C: Parse metadata and extract authorization server(s)
    Client determines AS to use

    C->>A: GET /.well-known/oauth-authorization-server
    A->>C: Authorization server metadata response

    alt Dynamic client registration
        C->>A: POST /register
        A->>C: Client Credentials
    end

    Note over C: Generate PKCE parameters
    Include resource parameter
    C->>B: Open browser with authorization URL + code_challenge + resource
    B->>A: Authorization request with resource parameter
    Note over A: User authorizes
    A->>B: Redirect to callback with authorization code
    B->>C: Authorization code callback
    C->>A: Token request + code_verifier + resource
    A->>C: Access token (+ refresh token)
    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token
```

--------------------------------

### mcp_server with invalid tools path

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/tools.md

Demonstrates the error when `tools` is provided as a path but is not a valid R file or list of tools.

```R
mcp_server(tmp_file)
```

--------------------------------

### set_server_tools with non-list input

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/tools.md

Illustrates the error when `set_server_tools` receives input that is not a list of tools or an R file path.

```R
set_server_tools(123)
```

--------------------------------

### Configure mcptools as MCP Server for Claude Desktop

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

Add mcptools as an MCP server in the Claude Desktop configuration file. This allows Claude Desktop to execute R code in your sessions.

```json
{
  "mcpServers": {
    "r-mcptools": {
      "command": "Rscript",
      "args": ["-e", "mcptools::mcp_server()"]
    }
  }
}
```

--------------------------------

### Mermaid Sequence Diagram for MCP Session

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/transports.md

Illustrates the sequence of interactions for MCP session initialization, client requests, server responses, and notifications.

```mermaid
sequenceDiagram
    participant Client
    participant Server

    note over Client, Server: initialization

    Client->>+Server: POST InitializeRequest
    Server->>-Client: InitializeResponse<br>Mcp-Session-Id: 1868a90c...

    Client->>+Server: POST InitializedNotification<br>Mcp-Session-Id: 1868a90c...
    Server->>-Client: 202 Accepted

    note over Client, Server: client requests
    Client->>+Server: POST ... request ...<br>Mcp-Session-Id: 1868a90c...

    alt single HTTP response
      Server->>Client: ... response ...
    else server opens SSE stream
      loop while connection remains open
          Server-)Client: ... SSE messages from server ...
      end
      Server-)Client: SSE event: ... response ...
    end
    deactivate Server

    note over Client, Server: client notifications/responses
    Client->>+Server: POST ... notification/response ...<br>Mcp-Session-Id: 1868a90c...
    Server->>-Client: 202 Accepted

    note over Client, Server: server requests
    Client->>+Server: GET<br>Mcp-Session-Id: 1868a90c...
    loop while connection remains open
        Server-)Client: ... SSE messages from server ...
    end
    deactivate Server

```

--------------------------------

### GitHub MCP Server Configuration

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

This JSON configuration registers the GitHub MCP server with mcptools. It specifies the command to run the server and environment variables, including a placeholder for your GitHub Personal Access Token.

```json
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}
```

--------------------------------

### Configure mcptools as MCP Server for Claude Code

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

Add mcptools as an MCP server using the 'claude mcp add' command. This command-line approach is an alternative to editing the configuration file directly.

```bash
claude mcp add -s "user" r-mcptools -- Rscript -e "mcptools::mcp_server()"
```

--------------------------------

### set_server_tools with reserved tool names

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/tools.md

Highlights the error when attempting to use tool names that are reserved by mcptools.

```R
set_server_tools(list(tls$value[[1]]))
```

--------------------------------

### Client Initialized Notification

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/lifecycle.md

After successful initialization, the client sends an 'initialized' notification to signal readiness for normal operations.

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

--------------------------------

### stdio Transport Sequence Diagram

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/transports.md

Illustrates the message exchange flow for the stdio transport, involving subprocess launch, message exchange via stdin/stdout, and optional stderr logging.

```mermaid
sequenceDiagram
    participant Client
    participant Server Process

    Client->>+Server Process: Launch subprocess
    loop Message Exchange
        Client->>Server Process: Write to stdin
        Server Process->>Client: Write to stdout
        Server Process--)Client: Optional logs on stderr
    end
    Client->>Server Process: Close stdin, terminate subprocess
    deactivate Server Process
```

--------------------------------

### MCP Authorization Server Metadata Discovery Flow

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/authorization.md

This diagram outlines the sequence of interactions between an MCP client, MCP server, and Authorization Server for discovering authorization server metadata.

```mermaid
sequenceDiagram
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M-->>C: HTTP 401 Unauthorized with WWW-Authenticate header
    Note over C: Extract resource_metadata<br />from WWW-Authenticate

    C->>M: GET /.well-known/oauth-protected-resource
    M-->>C: Resource metadata with authorization server URL
    Note over C: Validate RS metadata,
    build AS metadata URL

    C->>A: GET /.well-known/oauth-authorization-server
    A-->>C: Authorization server metadata

    Note over C,A: OAuth 2.1 authorization flow happens here

    C->>A: Token request
    A-->>C: Access token

    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token
```

--------------------------------

### Asynchronous I/O Operations in mcptools

Source: https://github.com/posit-dev/mcptools/blob/main/CLAUDE.md

Illustrates the use of asynchronous I/O operations like send_aio() and recv_aio(). These functions return immediately, allowing operations to complete in the background. Use unresolved(aio) to check pending status and access results via aio$data or aio$result.

```R
send_aio()
recv_aio()
unresolved(aio)
aio$data
aio$result
```

--------------------------------

### mcp_tools() Error: Invalid JSON Configuration

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/client.md

Triggers an error when the configuration file is not valid JSON. The error message indicates a lexical error within the JSON text.

```R
mcp_tools(tmp_file)
```

--------------------------------

### Calling mcp_server() in an Interactive Session

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/server.md

Demonstrates the expected error when mcp_server() is called interactively. This function is not intended for direct interactive use.

```R
mcp_server()

```

--------------------------------

### Register R Session with mcptools

Source: https://github.com/posit-dev/mcptools/blob/main/README.md

Call mcptools::mcp_session() within an R session to allow MCP-enabled tools to access variables in that specific session. Consider adding this to your .Rprofile for automatic registration.

```r
mcptools::mcp_session()
```

--------------------------------

### MCP Message Flow Diagram

Source: https://github.com/posit-dev/mcptools/blob/main/CLAUDE.md

Visualizes the message flow within the mcptools architecture, showing how requests and results are routed between the MCP Client, Server, and Session processes.

```text
MCP Client → Server (stdin) → Session (socket) → Server → Client (stdout)
```

--------------------------------

### mcp_tools() Error: Process Exits with Error

Source: https://github.com/posit-dev/mcptools/blob/main/tests/testthat/_snaps/client.md

Triggers an error when an underlying process, such as `Rscript`, fails during execution. The error message will detail the specific failure from the executed command.

```R
mcp_tools(tmpfile)
```

--------------------------------

### Resource Parameter in Authorization Request

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/authorization.md

When making an authorization request to an MCP server, the 'resource' parameter should be included with the URL-encoded canonical URI of the MCP server.

```http
&resource=https%3A%2F%2Fmcp.example.com
```

--------------------------------

### JSON-RPC Request Structure

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/basic.md

Requests initiate operations and must include a unique string or number ID, which cannot be null or previously used within the session.

```typescript
{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: {
    [key: string]: unknown;
  };
}
```

--------------------------------

### JSON-RPC Notification Structure

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/basic.md

Notifications are one-way messages that do not require a response and must not include an ID.

```typescript
{
  jsonrpc: "2.0";
  method: string;
  params?: {
    [key: string]: unknown;
  };
}
```

--------------------------------

### JSON-RPC Response Structure

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/basic.md

Responses reply to requests with either a result or an error, identified by the original request ID. Both result and error cannot be present simultaneously.

```typescript
{
  jsonrpc: "2.0";
  id: string | number;
  result?: {
    [key: string]: unknown;
  }
  error?: {
    code: number;
    message: string;
    data?: unknown;
  }
}
```

--------------------------------

### Authorization Header with Bearer Token

Source: https://github.com/posit-dev/mcptools/blob/main/inst/spec/authorization.md

MCP clients must use the Authorization request header field with the 'Bearer' scheme to include access tokens in HTTP requests to MCP servers.

```http
Authorization: Bearer <access-token>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.