### Install MCP with Server Configurations

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Installs the MCP package and configures various MCP servers like filesystem, fetch, qdrant, and graphlit. Ensures Emacs version 30 or higher is used. Starts all configured servers after initialization.

```elisp
(use-package mcp
    :ensure t
    :after gptel
    :custom (mcp-hub-servers
             `(("filesystem" . (:command "npx" 
                                :args ("-y" "@modelcontextprotocol/server-filesystem")
                                :roots ("/home/lizqwer/MyProject/")))
               ("fetch" . (:command "uvx" :args ("mcp-server-fetch")))
               ("qdrant" . (:url "http://localhost:8000/sse"))
               ("graphlit" . (
                              :command "npx"
                              :args ("-y" "graphlit-mcp-server")
                              :env ( 
                                    :GRAPHLIT_ORGANIZATION_ID "your-organization-id"
                                    :GRAPHLIT_ENVIRONMENT_ID "your-environment-id"
                                    :GRAPHLIT_JWT_SECRET "your-jwt-secret")))))
    :config (require 'mcp-hub)
    :hook (after-init . mcp-hub-start-all-server))
```

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

### Usage Examples

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/connection.md

Examples demonstrating how to create and interact with MCP connections.

```APIDOC
## Usage Examples

#### Creating an HTTP connection

```elisp
(make-instance 'mcp-http-process-connection
               :name "my-server"
               :connection-type 'http
               :host "localhost"
               :port 8000
               :path "/sse"
               :token "my-auth-token"
               :timeout 30)
```

#### Creating a stdio connection

```elisp
(make-instance 'mcp-stdio-process-connection
               :name "filesystem"
               :connection-type 'stdio
               :process (make-process :name "mcp-filesystem" :command '("npx" "@modelcontextprotocol/server-filesystem"))
               :timeout 30)
```

#### Accessing connection state

```elisp
(let ((conn (gethash "filesystem" mcp-server-connections)))
  ;; Check if connected
  (eq (mcp--status conn) 'connected)
  
  ;; Get available tools
  (mcp--tools conn)
  
  ;; Get server capabilities
  (mcp--capabilities conn)
  
  ;; Get current roots
  (mcp--roots conn))
```
```

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

### Example Server Capabilities

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of a server capabilities plist, showing specific settings for various features.

```elisp
(:roots (:listChanged t)
 :logging nil
 :tools t
 :prompts t
 :resources t)
```

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

### Install MCP with Use-Package

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Install the MCP package and require the mcp-hub module for server management.

```elisp
(use-package mcp
  :ensure t
  :config (require 'mcp-hub))
```

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

### Example MCP Tool Definition

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example illustrating a 'write_file' tool with its schema for path and content arguments.

```elisp
(:name "write_file"
 :description "Write content to a file"
 :inputSchema (:type "object"
               :properties (:path (:type "string" :description "File path")
                            :content (:type "string" :description "File content"))
               :required ["path" "content"])))
```

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

### Elisp Resource Example

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of a resource definition, specifying a user configuration file with its URI, name, description, and MIME type.

```elisp
(:uri "file:///home/user/config.json"
 :name "User Configuration"
 :description "Main user configuration file"
 :mimeType "application/json")
```

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

### Example gptel Tool Definition

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

A concrete example of a tool definition for gptel, demonstrating how to define a 'write_file' tool with its arguments.

```elisp
(:function (lambda (&rest args) ...)
 :name "write_file"
 :async nil
 :description "Write content to file"
 :args [(:name "path"
         :type "string"
         :description "File path")
        (:name "content"
         :type "string"
         :description "File content")]
 :category "mcp-filesystem")
```

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

### Start All MCP Servers

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Starts all configured MCP servers. Supports asynchronous or synchronous startup and filtering by server name. A callback function can be provided to execute upon completion.

```elisp
(defun mcp-hub-start-all-server (&optional callback servers syncp))
```

```elisp
(mcp-hub-start-all-server
 (lambda () 
 (message "All servers started")))
```

```elisp
;; Start only specific servers
(mcp-hub-start-all-server nil '("filesystem" "fetch"))
```

```elisp
;; Synchronous start
(mcp-hub-start-all-server nil nil t)
```

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

### Server Information Example

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of server information, providing values for the server's name, version, and description. Used to identify and describe an MCP server.

```elisp
(:name "filesystem-server"
 :version "1.0.0"
 :description "MCP server for filesystem operations")
```

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

### Start Selected MCP Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Starts the MCP server that the cursor is currently positioned over in the `*Mcp-Hub*` buffer.

```elisp
(defun mcp-hub-start-server ())
```

```elisp
;; In *Mcp-Hub* buffer, position cursor on server row
;; Press 's' or M-x mcp-hub-start-server
```

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

### Get and display server roots

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-get-roots to retrieve the list of roots for a server and then iterating through them to display their paths or URIs and names.

```elisp
(let ((roots (mcp-get-roots "filesystem")))
  (dolist (root roots)
    (if (stringp root)
        (message "Root path: %s" root)
      (message "Root: %s (%s)"
               (plist-get root :uri)
               (plist-get root :name)))))

```

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

### mcp-hub-start-all-server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Starts all configured MCP servers. It can optionally take a callback function, a list of specific servers to start, and a flag for synchronous startup.

```APIDOC
## mcp-hub-start-all-server

### Description
Start all configured MCP servers.

### Function Signature
```elisp
(defun mcp-hub-start-all-server (&optional callback servers syncp))
```

### Parameters
#### Optional Parameters
- **callback** (function) - Called when all servers started
- **servers** (list) - Filter: list of server names to start (nil = all)
- **syncp** (boolean) - Use synchronous (t) or asynchronous (nil) startup

### Return Value
Returns nil. Displays status messages.

### Examples
```elisp
;; Start all servers with a callback
(mcp-hub-start-all-server
 (lambda () (message "All servers started")))

;; Start only specific servers
(mcp-hub-start-all-server nil '("filesystem" "fetch"))

;; Synchronous start
(mcp-hub-start-all-server nil nil t)
```
```

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

### Open MCP Hub and Start Servers

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Opens the MCP Hub interface and starts all configured servers. This is achieved by passing `t` as an argument to the `mcp-hub` function.

```elisp
(mcp-hub t)
```

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

### Get simple prompt synchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Example of retrieving a prompt with arguments using mcp-get-prompt. Ensure the connection is established and the prompt name is valid.

```emacs-lisp
(let ((connection (gethash "everything" mcp-server-connections)))
  (let ((result (mcp-get-prompt connection "complex_prompt" '(:temperature "1.0"))))
    (message "Prompt: %s" result)))
```

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

### Synchronously Get Prompt

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Retrieve a prompt synchronously from a server. This example uses the 'everything' server as the 'filesystem' server lacks prompts. It includes parameters for the prompt request.

```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-get-prompt connection "complex_prompt" '(:temperature "1.0")))
```

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

### Start All MCP Servers on Emacs Initialization

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Adds a hook to start all configured MCP servers automatically after Emacs has finished initializing. This ensures servers are ready when Emacs starts.

```elisp
(add-hook 'after-init-hook
            #'mcp-hub-start-all-server)
```

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

### Configure and Launch MCP Hub

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Defines server configurations for the MCP hub and then launches the hub interface, starting all configured servers.

```elisp
(setq mcp-hub-servers
      '(("filesystem" . (:command "npx"
                        :args ("-y" "@modelcontextprotocol/server-filesystem")
                        :roots ("/home/user/project")))))

(mcp-hub t)  ;; Launch hub and start all servers
```

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

### Elisp Prompt Example

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of a prompt definition, specifying a greeting prompt with 'name' and 'tone' arguments.

```elisp
(:name "greeting_prompt"
 :description "Generate a greeting message"
 :arguments [(:name "name"
              :description "Person to greet"
              :required t)
             (:name "tone"
              :description "Tone of greeting"
              :required nil)])
```

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

### Example Usage of mcp-hub-detail--display-resource

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/resources.md

Demonstrates how to use `mcp-hub-detail--display-resource` by first reading a resource and then passing the result and URI to the display function.

```elisp
(let ((result (mcp-read-resource conn "file:///path/to/file")))
  (mcp-hub-detail--display-resource result "file:///path/to/file"))
```

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

### Root Definition Example

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of a root definition in plist form, specifying the file URI and a display name. Used for configuring project roots in MCP.

```elisp
(:uri "file:///home/user/MyProject"
 :name "My Project")
```

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

### Create Asynchronous Tool

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/tools.md

Example of creating and using an asynchronous gptel tool generated by `mcp-make-text-tool`.

```elisp
(let ((tool (mcp-make-text-tool "filesystem" "write_file" t)))
  (funcall (plist-get tool :function)
           (lambda (result)
             (message "Result: %s" result))
           "/tmp/test.txt" "content"))
```

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

### Connect to Filesystem Server (stdio)

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Example of connecting to a filesystem server using stdio. It specifies the command, arguments, roots, and provides callbacks for initialization and tool listing.

```elisp
(mcp-connect-server "filesystem"
                    :command "npx"
                    :args '("-y" "@modelcontextprotocol/server-filesystem")
                    :roots '("/home/user/project")
                    :initial-callback
                    (lambda (conn)
                      (message "Connected to %s" (jsonrpc-name conn)))
                    :tools-callback
                    (lambda (conn tools)
                      (message "Available tools: %s" (length tools))))
```

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

### Example MCP Tool Result

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of a tool result indicating successful file writing.

```elisp
(:content [(:type "text"
            :text "File written successfully")])
```

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

### Set roots as simple paths

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-set-roots to set server roots using a list of simple directory paths.

```elisp
(mcp-set-roots "filesystem"
               '("/home/user/project1"
                 "/home/user/project2"))
```

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

### Create Synchronous Tool

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/tools.md

Example of creating and using a synchronous gptel tool generated by `mcp-make-text-tool`.

```elisp
(let ((tool (mcp-make-text-tool "filesystem" "write_file")))
  ;; tool can be passed to gptel
  (funcall (plist-get tool :function) "/tmp/test.txt" "content"))
```

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

### Connect to HTTP/SSE Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Example of connecting to an HTTP/SSE server. It includes the server URL, authentication token, custom headers, and a request timeout.

```elisp
(mcp-connect-server "qdrant"
                    :url "http://localhost:8000/sse"
                    :token "my-auth-token"
                    :headers '(("X-Custom-Header" . "value"))
                    :timeout 30)
```

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

### mcp-hub-start-server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Starts the selected MCP server. This function requires the cursor to be on a server row in the \*Mcp-Hub\* buffer.

```APIDOC
## mcp-hub-start-server

### Description
Start the selected server.

### Function Signature
```elisp
(defun mcp-hub-start-server ())
```

### Usage
Requires cursor to be on a server row in \*Mcp-Hub\* buffer.

### Examples
```elisp
;; In *Mcp-Hub* buffer, position cursor on server row
;; Press 's' or M-x mcp-hub-start-server
```
```

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

### Create a Stdio MCP Connection

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/connection.md

Example of creating an instance of mcp-stdio-process-connection. This involves specifying the process to run, such as a Node.js server command.

```elisp
(make-instance 'mcp-stdio-process-connection
               :name "filesystem"
               :connection-type 'stdio
               :process (make-process :name "mcp-filesystem" :command '("npx" "@modelcontextprotocol/server-filesystem"))
               :timeout 30)
```

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

### Resource Template Example

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/types.md

An example of a resource template definition with specific values for URI template, name, description, and MIME type. Used to represent a resource template pattern on an MCP server.

```elisp
(:uriTemplate "database://users/{id}"
 :name "User Record Template"
 :description "Access user records by ID"
 :mimeType "application/json")
```

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

### Configure MCP Server

Source: https://github.com/lizqwerscott/mcp.el/wiki/quickstart.org

Configure the MCP server by setting the server name, command, and arguments. This example configures the 'fetch' MCP server.

```emacs-lisp
(require 'mcp-hub)
  (setq mcp-hub-servers
        '(("fetch" . (:command "uvx" :args ("mcp-server-fetch")))))

```

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

### Data Flow Example

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Illustrates the typical data flow when interacting with an MCP server, from user code to API calls and results.

```text
User Code
    ↓
mcp-connect-server (establish connection)
    ↓
Connection Type: Stdio or HTTP/SSE
    ↓
JSON-RPC Message Exchange
    ↓
Tool/Prompt/Resource APIs
    ↓
Results returned to callbacks or synchronously
```

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

### Asynchronously Get Prompt

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Retrieve a prompt asynchronously from a server, using callback functions to handle the response or errors. This example uses the 'everything' server.

```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-async-get-prompt connection
                          "complex_prompt"
                          '(:temperature "1.0")
                          #'(lambda (res)
                              (message "prompt: %s" res))
                          #'(lambda (code message)
                              (message "error call: %s, %s" code message))))
```

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

### Batch Start All Servers

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Use `mcp-hub-start-all-server` to start all configured MCP servers simultaneously. This is a convenience function for managing multiple server instances.

```emacs-lisp
(mcp-hub-start-all-server)
```

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

### Add simple path root

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-add-root to add a root directory using a simple string path.

```elisp
(mcp-add-root "filesystem" "/home/user/new-project")
```

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

### Create an HTTP MCP Connection

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/connection.md

Example of creating an instance of mcp-http-process-connection. Specify connection details like host, port, path, and authentication token.

```elisp
(make-instance 'mcp-http-process-connection
               :name "my-server"
               :connection-type 'http
               :host "localhost"
               :port 8000
               :path "/sse"
               :token "my-auth-token"
               :timeout 30)
```

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

### Set roots with metadata

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-set-roots to set server roots with metadata, including URIs and names, alongside simple paths.

```elisp
(mcp-set-roots "filesystem"
               '((:uri "file:///home/user/project1" :name "Main Project")
                 (:uri "file:///home/user/project2" :name "Secondary Project")
                 "/home/user/downloads"))
```

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

### Add root with metadata

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-add-root to add a root directory with associated metadata, such as URI and name.

```elisp
(mcp-add-root "filesystem"
              '(:uri "file:///home/user/new-project" :name "New Project"))
```

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

### Dispatch mcp-request-dispatcher for roots/list

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-request-dispatcher to request the list of roots for a server.

```elisp
(mcp-request-dispatcher name 'roots/list params)
```

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

### Check if Server is Running

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Example of checking if the 'filesystem' server is running. If it is, a message is displayed indicating its operational status.

```elisp
(when (mcp--server-running-p "filesystem")
  (message "Server is running"))
```

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

### Read a Simple Text Resource

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/resources.md

Example of how to read a simple text resource using mcp-read-resource and display its content. Ensure the 'everything' connection is established.

```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
  (let ((result (mcp-read-resource connection "test://static/resource/1")))
    (let ((text (mcp--parse-tool-call-result result)))
      (message "Resource content: %s" text))))
```

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

### Configure MCP Server Start Time

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/configuration.md

Sets the maximum seconds to wait for server initialization. Controls the timeout for the initial :initialize request.

```elisp
(defcustom mcp-server-start-time 60
  :group 'mcp
  :type 'integer)
```

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

### Configure and Launch Hub Servers

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/README.md

Defines the servers to be managed by the MCP hub, including their commands, arguments, and root directories. The `mcp-hub` function is then called to launch and start all configured servers.

```elisp
(setq mcp-hub-servers
      '(("filesystem" . (:command "npx"
                        :args ("-y" "@modelcontextprotocol/server-filesystem")
                        :roots ("/home/user/project")))
        ("fetch" . (:command "uvx" :args ("mcp-server-fetch")))))

(mcp-hub t)  ;; Launch and start all servers
```

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

### Call MCP Hub View Log Function

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Example of how to call the mcp-hub-view-log function from the *Mcp-Hub* buffer. This is typically triggered by pressing 'l'.

```elisp
(mcp-hub-view-log)
```

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

### Open MCP Hub Interactively

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Opens the MCP Hub interface and starts all configured servers when invoked interactively with a prefix argument (e.g., `M-u M-x mcp-hub`).

```elisp
M-u M-x mcp-hub  ;; starts all servers
```

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

### Get List of Resources Synchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/resources.md

Retrieves a list of available resources synchronously. Use this when immediate access to the resource list is required.

```elisp
(defun mcp-sync-list-resources (connection &optional callback error-callback))
```

```elisp
(let ((resources (mcp-sync-list-resources connection)))
  (message "Available resources: %s" (length resources)))
```

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

### Get prompt asynchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Example of asynchronously retrieving a prompt using mcp-async-get-prompt. This method is non-blocking and uses callbacks for results.

```emacs-lisp
(let ((connection (gethash "everything" mcp-server-connections)))
  (mcp-async-get-prompt connection
                        "complex_prompt"
                        '(:temperature "1.0")
                        (lambda (res)
                          (message "Prompt: %s" res))
                        (lambda (code message)
                          (message "Error %s: %s" code message))))
```

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

### Connect to MCP Server and Call Tool

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/README.md

Demonstrates how to establish a connection to an MCP server, wait for it to become available, and then call a specific tool with arguments. Ensure the server details and tool path are correctly specified.

```elisp
;; Connect
(mcp-connect-server "myserver"
                    :command "npx"
                    :args '("-y" "@modelcontextprotocol/server-filesystem")
                    :roots '("/home/user/project"))

;; Wait for connection
(sleep-for 1)

;; Call tool
(let ((conn (gethash "myserver" mcp-server-connections)))
  (let ((result (mcp-call-tool conn "read_file" '(:path "/tmp/test.txt"))))
    (message "Content: %s" result)))
```

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

### Get prompt without arguments synchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Example of retrieving a prompt without any arguments using mcp-get-prompt. This is useful for prompts that do not require input.

```emacs-lisp
(let ((connection (gethash "server" mcp-server-connections)))
  (let ((result (mcp-get-prompt connection "greeting" nil)))
    (message "Greeting: %s" result)))
```

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

### Send Notification to Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Example of sending a notification to an MCP server. This snippet shows how to retrieve a connection and send a notification, both with and without parameters.

```elisp
(let ((conn (gethash "filesystem" mcp-server-connections)))
  ;; Notify roots changed
  (mcp-notify conn :notifications/roots/list_changed))

;; With parameters
(let ((conn (gethash "qdrant" mcp-server-connections)))
  (mcp-notify conn :custom/notification '(:data "some-value")))
```

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

### Get List of Resource Templates Synchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/resources.md

Retrieves a list of resource templates synchronously. Use this when immediate access to the template list is required.

```elisp
(defun mcp-sync-list-resource-templates (connection &optional callback error-callback))
```

```elisp
(let ((templates (mcp-sync-list-resource-templates connection)))
  (message "Available resource templates: %s" (length templates)))
```

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

### Open MCP Hub

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Opens the MCP Hub interface without starting any servers. This is the default behavior when called without arguments.

```elisp
(mcp-hub)
```

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

### Get All Tools Synchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Retrieves all available tools from connected servers synchronously. Iterates through the returned list of tool plists and prints each tool's name.

```elisp
(cl-defun mcp-hub-get-all-tool (&key asyncp categoryp))
```

```elisp
(let ((all-tools (mcp-hub-get-all-tool)))
  (dolist (tool all-tools)
    (message "Tool: %s" (plist-get tool :name))))
```

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

### mcp-sync-list-prompts

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Get list of available prompts synchronously. This function retrieves prompts directly and returns the list or invokes an error callback.

```APIDOC
## mcp-sync-list-prompts

### Description
Get list of available prompts synchronously. This function retrieves prompts directly and returns the list or invokes an error callback.

### Function Signature
```elisp
(defun mcp-sync-list-prompts (connection &optional callback error-callback))
```

### Parameters
#### Parameters
- **connection** (mcp-process-connection) - Required - MCP connection
- **callback** (function) - Optional - Called with (connection prompts) on success
- **error-callback** (function) - Optional - Called with (code message) on error

### Return Value
Returns vector of prompt definitions or calls callback with results.

### Examples
```elisp
(let ((prompts (mcp-sync-list-prompts connection)))
  (message "Available prompts: %s" (length prompts)))
```
```

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

### Get Tool List Synchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/tools.md

Retrieves a list of available tools synchronously. Use this when immediate access to the tool list is required and blocking is acceptable.

```elisp
(defun mcp-sync-list-tools (connection &optional callback error-callback))
```

```elisp
(let ((tools (mcp-sync-list-tools connection)))
  (message "Available tools: %s" (length tools)))
```

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

### Get Async Tools with Category

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Retrieves asynchronous tools from connected servers, including category information for each tool. Iterates through the results and prints the tool name and its category.

```elisp
(let ((all-tools (mcp-hub-get-all-tool :asyncp t :categoryp t)))
  (dolist (tool all-tools)
    (message "Tool %s (category: %s)" 
             (plist-get tool :name)
             (plist-get tool :category))))
```

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

### Handle Process Start Error in Elisp

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/errors.md

Catch errors when the MCP server process fails to spawn. The error callback receives a code of -1 for process errors.

```elisp
(mcp-connect-server "server"
                    :command "invalid-command"
                    :error-callback
                    (lambda (code message)
                      (message "Connection failed: %s" message)))
```

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

### Handle Tool Argument Mismatch

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/errors.md

Handle potential errors when calling a tool, specifically argument mismatches, using `condition-case-unless-debug`. This example uses `mcp-make-text-tool` and demonstrates catching generic 'error' conditions.

```elisp
;; Error handling is built into tool function
(let ((tool (mcp-make-text-tool "server" "write_file")))
  (condition-case err
      (funcall (plist-get tool :function) "/path" "content")
    (error (message "Tool error: %s" err))))
```

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

### Connect to an MCP Filesystem Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Establishes a connection to an MCP server, specifically a 'filesystem' server. It defines the command, arguments, and root directories for the server, and sets up callbacks for initial connection and tool updates.

```elisp
(mcp-connect-server "filesystem" 
                      :command "npx" 
                      :args '("-y" "@modelcontextprotocol/server-filesystem")
                      :roots '("~/Downloads/" "~/Documents/")
                      :initial-callback
                      #'(lambda (connection)
                          (message "%s connection" (jsonrpc-name connection)))
                      :tools-callback
                      #'(lambda (connection tools)
                          (message "%s tools: %s" (jsonrpc-name connection) tools))
```

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

### Async List Tools with Callback

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/README.md

Shows how to asynchronously list available tools on a connection and process the results using a callback function. The callback receives the connection object and a list of tools.

```elisp
(mcp-async-list-tools connection
                      (lambda (conn tools)
                        (message "Got %d tools" (length tools))))
```

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

### mcp-hub-restart-all-server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Restarts all configured MCP servers by stopping them first and then starting them again.

```APIDOC
## mcp-hub-restart-all-server

### Description
Restart all configured MCP servers.

### Function Signature
```elisp
(defun mcp-hub-restart-all-server ())
```

### Details
Stops all servers then starts them again.

### Return Value
Returns nil.

### Examples
```elisp
(mcp-hub-restart-all-server)
```
```

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

### Connect to an MCP Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Establishes a connection to an MCP server with specified command, arguments, and root directories. A callback function is provided to log the connection name upon successful connection.

```elisp
(mcp-connect-server "my-server"
                    :command "npx"
                    :args '("-y" "@modelcontextprotocol/server-filesystem")
                    :roots '("/home/user/project")
                    :initial-callback
                    (lambda (conn)
                      (message "Connected to %s" (jsonrpc-name conn))))
```

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

### Restart All MCP Servers

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Restarts all configured MCP servers by stopping them first and then starting them again.

```elisp
(defun mcp-hub-restart-all-server ())
```

```elisp
(mcp-hub-restart-all-server)
```

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

### Initial Callback Signature

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/configuration.md

This callback is invoked upon successful server initialization. It receives the connection object as an argument.

```elisp
(lambda (connection)
  (message "Server initialized: %s" (jsonrpc-name connection)))
```

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

### mcp-hub

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Displays the MCP Hub server management interface. It can optionally start all configured servers.

```APIDOC
## mcp-hub

### Description
Display the MCP Hub server management interface. This function can optionally start all servers.

### Function Signature
```elisp
(defun mcp-hub (&optional start))
```

### Parameters
#### Optional Parameters
- **start** (boolean) - If true or called interactively with a prefix argument, all servers will be started.

### Return Value
Returns nil. Displays the `*Mcp-Hub*` buffer with the server list.

### Behavior
- Creates the `*Mcp-Hub*` buffer if it does not exist.
- Switches to the buffer using `pop-to-buffer`.
- Initializes `mcp-hub-mode` major mode.
- Optionally starts all configured servers.

### Examples
#### Open hub without starting servers
```elisp
(mcp-hub)
```

#### Open hub and start all servers
```elisp
(mcp-hub t)
```

#### Interactively with prefix argument
```elisp
M-u M-x mcp-hub  ;; starts all servers
```
```

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

### Synchronous Server Connection

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Demonstrates establishing a synchronous connection to a server, useful for blocking operations where immediate feedback is required.

```elisp
(mcp-connect-server "filesystem"
                    :command "npx"
                    :args '("-y" "@modelcontextprotocol/server-filesystem")
                    :syncp t)
```

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

### mcp-hub-restart-server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Restarts the selected MCP server by stopping it and then starting it again. This function requires the cursor to be on a server row.

```APIDOC
## mcp-hub-restart-server

### Description
Restart the selected server.

### Function Signature
```elisp
(defun mcp-hub-restart-server ())
```

### Details
Stops then starts the server.

```

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

### Remove simple path root

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-remove-root to remove a root directory specified by its string path.

```elisp
(mcp-remove-root "filesystem" "/home/user/old-project")
```

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

### List Tools Synchronously and Asynchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Demonstrates how to list available tools using both blocking synchronous calls and non-blocking asynchronous calls. The asynchronous version requires a callback function to process the results.

```elisp
;; Synchronous (blocks)
(let ((tools (mcp-sync-list-tools connection)))
  (message "Tools: %s" (length tools)))

;; Asynchronous (non-blocking)
(mcp-async-list-tools connection
                      (lambda (conn tools)
                        (message "Tools: %s" (length tools))))
```

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

### Remove root by uri plist

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of using mcp-remove-root to remove a root directory specified by its plist containing the URI.

```elisp
(mcp-remove-root "filesystem"
                 '(:uri "file:///home/user/old-project" :name "Old Project"))
```

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

### Stop Filesystem Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Example of stopping the 'filesystem' MCP server. This action disconnects the client and cleans up server resources.

```elisp
(mcp-stop-server "filesystem")
```

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

### Configuring Request Timeouts

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/errors.md

Demonstrates how to set the global default timeout for JSONRPC requests using `mcp-server-start-time` and how to set a per-connection timeout during server connection.

```elisp
;; Set global timeout
(setq mcp-server-start-time 120)  ;; for initialization

;; Set per-connection timeout
(mcp-connect-server "server"
                    :command "..."
                    :timeout 60)
```

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

### Restart Selected MCP Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Restarts the MCP server that the cursor is currently positioned over in the `*Mcp-Hub*` buffer by stopping and then starting it.

```elisp
(defun mcp-hub-restart-server ())
```

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

### Integrate MCP Tools with gptel

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Shows how to retrieve all tools from all servers managed by MCP and append them to the `gptel-tools` variable for use within gptel.

```elisp
;; Get all tools from all servers
(let ((tools (mcp-hub-get-all-tool :categoryp t)))
  (setq gptel-tools (append gptel-tools tools)))
```

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

### Get Current Roots

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Use `mcp-get-roots` to retrieve the list of currently configured root directories for the MCP server.

```emacs-lisp
(mcp-get-roots)
```

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

### mcp-get-prompt

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Synchronously retrieve a prompt from the MCP server. This function is used to get prompt data directly and wait for the response.

```APIDOC
## mcp-get-prompt

### Description
Synchronously retrieve a prompt from the MCP server.

### Function Signature
```elisp
(defun mcp-get-prompt (connection name arguments))
```

### Parameters
#### Path Parameters
- **connection** (mcp-process-connection) - MCP connection object
- **name** (string) - Name of the prompt to retrieve
- **arguments** (plist) - Plist of argument names and values

### Return Value
Returns plist containing prompt data. Structure depends on the prompt definition from server.

### Throws
- Signals `jsonrpc-error` if the prompt request fails

### Examples
#### Get simple prompt
```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
  (let ((result (mcp-get-prompt connection "complex_prompt" '(:temperature "1.0"))))
    (message "Prompt: %s" result)))
```

#### Get prompt without arguments
```elisp
(let ((connection (gethash "server" mcp-server-connections)))
  (let ((result (mcp-get-prompt connection "greeting" nil)))
    (message "Greeting: %s" result)))
```
```

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

### Fetch Server Configuration (stdio)

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/configuration.md

Configures a fetch server using stdio, specifying the command and its arguments.

```emacs-lisp
(setq mcp-hub-servers
      '(("fetch" . (:command "uvx"
                    :args ("mcp-server-fetch")))))

```

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

### Synchronously Read Resource with Everything Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Use this to synchronously read a resource from the 'everything' server. Ensure the 'everything' server connection is established.

```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-read-resource connection "test://static/resource/1"))
```

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

### Asynchronously Read Resource with Everything Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Use this to asynchronously read a resource from the 'everything' server. A callback function is provided to handle the resource once it's read. Ensure the 'everything' server connection is established.

```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-async-read-resource connection "test://static/resource/1"
                             #'(lambda (resource)
                                 (message "res: %s" resource))))
```

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

### Define mcp-hub Function

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/hub.md

Defines the `mcp-hub` function which displays the MCP Hub server management interface. It can optionally start all servers.

```elisp
(defun mcp-hub (&optional start))
```

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

### Synchronously Get Prompt

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Use `mcp-get-prompt` to retrieve a prompt from the MCP server synchronously. This function blocks until the prompt is received.

```emacs-lisp
(mcp-get-prompt "prompt-name")
```

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

### Configure MCP Server Initial Wait Time

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/configuration.md

Sets the seconds to wait after server initialization before fetching tools, prompts, and resources. Gives the server time to fully initialize all components.

```elisp
(defcustom mcp-server-wait-initial-time 2
  :group 'mcp
  :type 'integer)
```

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

### Use Tool with GPTEL

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/tools.md

Demonstrates how to add a tool created by `mcp-make-text-tool` to the `gptel-tools` list.

```elisp
(let ((tool (mcp-make-text-tool "filesystem" "write_file")))
  (push tool gptel-tools))
```

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

### Detailed JSONRPC Error Handling

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/errors.md

This example uses `condition-case-unless-debug` and `pcase` to specifically handle `jsonrpc-error` by extracting and displaying the error code and message.

```elisp
(condition-case-unless-debug err
    (mcp-call-tool conn "tool_name" '(:arg "value"))
  (jsonrpc-error
   (pcase err
     (`(jsonrpc-error ,_ (jsonrpc-error-code . ,code)
                      (jsonrpc-error-message . ,message) ,_)
      (message "Server error %s: %s" code message)))))
```

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

### Filesystem Server Configuration (stdio)

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/configuration.md

Configures a filesystem server using stdio, specifying the command and directory roots to expose.

```emacs-lisp
(setq mcp-hub-servers
      '(("filesystem" . (:command "npx"
                        :args ("-y" "@modelcontextprotocol/server-filesystem")
                        :roots ("/home/user/project"
                                "/home/user/documents")))))

```

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

### Connect to Filesystem Server with Plist Roots

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Connect to a filesystem server, specifying roots as a property list (plist) which allows for additional metadata like URIs and names. Non-plist entries are treated as simple file paths.

```elisp
(mcp-connect-server "filesystem"
                      :command "npx"
                      :args '("-y" "@modelcontextprotocol/server-filesystem")
                      :roots '((:uri "file:///home/user/project" :name "My Project")
                               "/home/user/downloads"))
```

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

### Get Tool List Asynchronously

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/tools.md

Retrieves a list of available tools asynchronously. This function is suitable for non-blocking operations where a callback handles the results.

```elisp
(defun mcp-async-list-tools (connection &optional callback error-callback))
```

```elisp
(mcp-async-list-tools connection
                      (lambda (conn tools)
                        (message "Tools: %s" (length tools))))
```

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

### Connect to Filesystem Server with Roots

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Connect to a filesystem server, specifying directories it can access using the :roots parameter. This replaces command-line arguments for directory specification.

```elisp
(mcp-connect-server "filesystem" 
                      :command "npx" 
                      :args '("-y" "@modelcontextprotocol/server-filesystem")
                      :roots '("/home/user/project1" "/home/user/project2"))
```

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

### Call a Tool on an MCP Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Retrieves a connection for 'my-server', then calls the 'read_file' tool with a specific path. The result is parsed and displayed.

```elisp
(let ((conn (gethash "my-server" mcp-server-connections)))
  (let ((result (mcp-call-tool conn "read_file" '(:path "/tmp/test.txt"))))
    (message "File content: %s" (mcp--parse-tool-call-result result))))
```

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

### Synchronously List Prompts

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Use this function to get a list of available prompts. This function will block until the prompts are retrieved. The results are returned directly.

```elisp
(defun mcp-sync-list-prompts (connection &optional callback error-callback))
```

```elisp
(let ((prompts (mcp-sync-list-prompts connection)))
  (message "Available prompts: %s" (length prompts)))
```

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

### Asynchronously List Resource Templates

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Use this to asynchronously list resource templates available from a server. A callback function is provided to process the list of templates. Ensure the server connection is established.

```elisp
(let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-async-list-resource-templates connection
                                       #'(lambda (connection templates)
                                           (message "%s" templates))))
```

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

### Synchronously List Available Tools

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Use `mcp-sync-list-tools` to fetch a list of available tools from the MCP server synchronously.

```emacs-lisp
(mcp-sync-list-tools)
```

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

### Notify roots list changed

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/roots.md

Example of manually sending a notification that the roots list has changed. This is typically handled automatically by other root management functions.

```elisp
(mcp-notify connection :notifications/roots/list_changed)
```

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

### Accessing Tools from Connection Object

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/tools.md

Demonstrates how to retrieve the vector of available tools associated with a given connection object.

```elisp
(mcp--tools connection)  ;; returns vector of tools
```

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

### Configure MCP Servers

Source: https://github.com/lizqwerscott/mcp.el/blob/master/Readme.org

Sets the list of MCP servers to be configured. This includes specifying the command, arguments, roots, URL, and environment variables for different server types.

```elisp
(setq mcp-hub-servers
        '(("filesystem" . (:command "npx" 
                           :args ("-y" "@modelcontextprotocol/server-filesystem")
                           :roots ("/home/lizqwer/MyProject/")))
          ("fetch" . (:command "uvx" :args ("mcp-server-fetch")))
          ("qdrant" . (:url "http://localhost:8000/sse"))
          ("graphlit" . (
                          :command "npx"
                          :args ("-y" "graphlit-mcp-server")
                          :env ( 
                                :GRAPHLIT_ORGANIZATION_ID "your-organization-id"
                                :GRAPHLIT_ENVIRONMENT_ID "your-environment-id"
                                :GRAPHLIT_JWT_SECRET "your-jwt-secret")))))
```

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

### Set Initialization Log Level

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/README.md

Configures the log level for MCP initialization. Set to 'debug' for more verbose logging during startup.

```elisp
(setq mcp-log-level 'debug)
```

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

### mcp-async-list-prompts

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Get list of available prompts asynchronously. This function initiates an asynchronous request to fetch prompts and provides callbacks for success and error handling.

```APIDOC
## mcp-async-list-prompts

### Description
Get list of available prompts asynchronously. This function initiates an asynchronous request to fetch prompts and provides callbacks for success and error handling.

### Function Signature
```elisp
(defun mcp-async-list-prompts (connection &optional callback error-callback))
```

### Parameters
#### Parameters
- **connection** (mcp-process-connection) - Required - MCP connection
- **callback** (function) - Optional - Called with (connection prompts) on success
- **error-callback** (function) - Optional - Called with (code message) on error

### Return Value
Returns nil. Callback is called with vector of prompts or error callback is invoked.

### Examples
```elisp
(mcp-async-list-prompts connection
                        (lambda (conn prompts)
                          (message "Available prompts: %s" (length prompts))))
```
```

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

### Establish Connection to MCP Server

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Use `mcp-connect-server` to establish a connection to an MCP server. This function is the entry point for interacting with MCP services.

```emacs-lisp
(mcp-connect-server "path/to/mcp/server")
```

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

### Access Server Connection from Hash Table

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/server-management.md

Demonstrates how to retrieve a specific server connection object from the global `mcp-server-connections` hash table using the server's name.

```elisp
(gethash "server-name" mcp-server-connections)
```

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

### HTTPS Server with Authentication

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/configuration.md

Configures an HTTPS server with authentication, including a token, environment variables, and headers.

```emacs-lisp
(setq mcp-hub-servers
      '(("graphlit" . (:url "https://api.example.com/mcp"
                       :token "your-auth-token"
                       :env (:GRAPHLIT_ORGANIZATION_ID "org-id"
                             :GRAPHLIT_ENVIRONMENT_ID "env-id"
                             :GRAPHLIT_JWT_SECRET "secret")))))

```

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

### Read Resource with Error Handling

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/resources.md

Demonstrates how to read a resource using mcp-read-resource and handle potential jsonrpc-error exceptions. This snippet shows a common pattern for robust resource fetching.

```elisp
(let ((connection (gethash "server" mcp-server-connections)))
  (condition-case err
      (let ((result (mcp-read-resource connection "file:///path/to/resource")))
        (message "Resource: %s" result))
    (jsonrpc-error
     (message "Failed to read resource: %s" (cdr err)))))
```

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

### Asynchronously List Available Tools

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/overview.md

Use `mcp-async-list-tools` to fetch a list of available tools asynchronously. A callback function can be provided to handle the results.

```emacs-lisp
(mcp-async-list-tools :callback #'my-tool-list-callback)
```

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

### Asynchronously List Prompts

Source: https://github.com/lizqwerscott/mcp.el/blob/master/_autodocs/api-reference/prompts.md

Use this function to get a list of available prompts without blocking the main thread. A callback function is invoked upon completion with the results or an error.

```elisp
(defun mcp-async-list-prompts (connection &optional callback error-callback))
```

```elisp
(mcp-async-list-prompts connection
                        (lambda (conn prompts)
                          (message "Available prompts: %s" (length prompts))))
```