Function: mcp-connect-server
mcp-connect-server is a natively compiled function defined in mcp.el.
Signature
(mcp-connect-server NAME &key COMMAND ARGS URL ENV TOKEN HEADERS ROOTS TIMEOUT INITIAL-CALLBACK TOOLS-CALLBACK PROMPTS-CALLBACK RESOURCES-CALLBACK RESOURCES-TEMPLATES-CALLBACK ERROR-CALLBACK SYNCP)
Documentation
Connect to an MCP server with NAME, COMMAND, and ARGS or URL.
NAME is a string representing the name of the server. COMMAND is a string representing the command to start the server in stdio mcp server. ARGS is a list of arguments to pass to the COMMAND. URL is a string arguments to connect sse mcp server. ENV is a plist argument to set mcp server env.
TOKEN is a string. Authentication token used when connecting to an HTTP MCP server.
HEADERS is a alist. Additional HTTP headers to include when connecting via URL.
ROOTS is a list of directory paths or root specifications.
Each root can be either:
- A string path (e.g., "/home/user/project")
- A plist with :uri and :name
(e.g., (:uri "file:///home/user/project" :name "Project"))
Roots define filesystem boundaries that the server can access.
TIMEOUT is the timeout in seconds for jsonrpc async requests.
Defaults to jsonrpc-default-request-timeout when nil.
INITIAL-CALLBACK is a function called when the server completes the connection. TOOLS-CALLBACK is a function called to handle the list of tools provided by the server. PROMPTS-CALLBACK is a function called to handle the list of prompts provided by the server. RESOURCES-CALLBACK is a function called to handle the list of resources provided by the server. RESOURCES-TEMPLATES-CALLBACK is a function called to handle the list of resources-templates provided by the server. ERROR-CALLBACK is a function to call on error. SYNCP specifies if the operation should be synchronous or asynchronous.
This function creates a new process for the server, initializes a connection, and sends an initialization message to the server. The connection is stored in the `mcp-server-connections` hash table for future reference.
Source Code
;; Defined in /nix/store/5m747x13pb1ddrvbq9raj91c4q1h1kl0-emacs-packages-deps/share/emacs/site-lisp/elpa/mcp-20260615.940/mcp.el
;;;###autoload
(cl-defun mcp-connect-server (name &key command args url env token headers roots
timeout
initial-callback tools-callback prompts-callback
resources-callback resources-templates-callback
error-callback syncp)
"Connect to an MCP server with NAME, COMMAND, and ARGS or URL.
NAME is a string representing the name of the server.
COMMAND is a string representing the command to start the server
in stdio mcp server.
ARGS is a list of arguments to pass to the COMMAND.
URL is a string arguments to connect sse mcp server.
ENV is a plist argument to set mcp server env.
TOKEN is a string.
Authentication token used when connecting to an HTTP MCP server.
HEADERS is a alist.
Additional HTTP headers to include when connecting via URL.
ROOTS is a list of directory paths or root specifications.
Each root can be either:
- A string path (e.g., \"/home/user/project\")
- A plist with :uri and :name
(e.g., (:uri \"file:///home/user/project\" :name \"Project\"))
Roots define filesystem boundaries that the server can access.
TIMEOUT is the timeout in seconds for jsonrpc async requests.
Defaults to `jsonrpc-default-request-timeout' when nil.
INITIAL-CALLBACK is a function called when the server completes
the connection.
TOOLS-CALLBACK is a function called to handle the list of tools
provided by the server.
PROMPTS-CALLBACK is a function called to handle the list of prompts
provided by the server.
RESOURCES-CALLBACK is a function called to handle the list of
resources provided by the server.
RESOURCES-TEMPLATES-CALLBACK is a function called to handle the list of
resources-templates provided by the server.
ERROR-CALLBACK is a function to call on error.
SYNCP specifies if the operation should be synchronous or asynchronous.
This function creates a new process for the server, initializes a connection,
and sends an initialization message to the server. The connection is stored
in the `mcp-server-connections` hash table for future reference."
(unless (mcp--server-running-p name)
(when-let* ((server-config (cond (command
(list :connection-type 'stdio
:command command
:args args))
(url
(when-let* ((res (mcp--parse-http-url url)))
(plist-put res :connection-type 'http)
(plist-put res :token token)
(plist-put res :headers headers)))))
(connection-type (plist-get server-config :connection-type))
(buffer-name (format "*Mcp %s server*" name))
(process-name (format "mcp-%s-server" name))
(process (pcase connection-type
('http 'empty)
('stdio
(let ((env (mapcar (lambda (item)
(pcase-let* ((`(,key ,value) item))
(let ((key (symbol-name key)))
(list (substring key 1)
(format "%s" value)))))
(seq-partition env 2)))
(process-environment (copy-sequence process-environment)))
(when env
(dolist (elem env)
(setenv (car elem) (cadr elem))))
(make-process
:name name
:command (append (list command)
(plist-get server-config :args))
:connection-type 'pipe
:coding 'utf-8-unix
;; :noquery t
:stderr (get-buffer-create
(format "*%s stderr*" name))
;; :file-handler t
))))))
(let ((connection (apply #'make-instance
`(,(pcase connection-type
('http
'mcp-http-process-connection)
('stdio
'mcp-stdio-process-connection))
:connection-type ,connection-type
:name ,name
:process ,process
:roots ,roots
:timeout ,(or timeout jsonrpc-default-request-timeout)
:events-buffer-config (:size ,mcp-log-size)
:request-dispatcher ,(lambda (_ method params)
(funcall #'mcp-request-dispatcher name method params))
:notification-dispatcher ,(lambda (connection method params)
(funcall #'mcp-notification-dispatcher connection name method params))
:on-shutdown ,(lambda (_)
(funcall #'mcp-on-shutdown name))
:initial-callback ,initial-callback
:prompts-callback ,prompts-callback
:tools-callback ,tools-callback
:resources-callback ,resources-callback
:resources-templates-callback ,resources-templates-callback
:error-callback ,error-callback
,@(when (equal connection-type 'http)
(list :host (plist-get server-config :host)
:port (plist-get server-config :port)
:tls (plist-get server-config :tls)
:path (plist-get server-config :path)
:token (plist-get server-config :token)
:headers (plist-get server-config :headers)))))))
;; Initialize connection
(puthash name connection mcp-server-connections)
;; Send the Initialize message
(let* ((msg-fn (lambda ()
(condition-case-unless-debug err
(if (jsonrpc-running-p connection)
(when (or (equal connection-type 'stdio)
(equal connection-type 'http))
(mcp--send-initial-message connection t syncp))
(error "Process start error"))
(error
(mcp-stop-server (jsonrpc-name connection))
(setf (mcp--status connection) 'error)
(when error-callback
(funcall error-callback -1 (format "%s" (cdr err))))
(message "Sadly, %s mcp server process start error" name))))))
(if (not syncp)
(run-with-idle-timer 1 nil msg-fn)
(sit-for 1)
(funcall msg-fn)))))))