MCP Server

Self-Hosting Documentation Access

This section requires a password to access. Interested in self-hosting? Contact sales to learn more.

Password:

Access Documentation

Self-Hosting Documentation Access Granted Logout

The LlamaParse MCP server exposes your deployment’s document-processing capabilities as tools any MCP-compatible agent can call. Self-hosted deployments run their own copy, so documents and API keys stay inside your network — agents talk to your MCP server, and it talks to your LlamaCloud backend over the cluster’s internal network.

Enable the server

values.yaml

config:
  mcp:
    enabled: true

The MCP server is released from its own repository, so its version does not track the chart’s. The chart pins a published tag for you, and there is normally nothing to set. Override it — under the top-level mcp key, not config.mcp — if you mirror images into your own registry, or to move to a newer MCP release than the one your chart version pins:

mcp:
  image: your-registry.example/llamacloud-mcp:<tag>

A pod reporting ImagePullBackOff is almost always this: a cluster that cannot reach the default registry, and no mirrored tag set here.

By default the server calls the LlamaCloud backend at its in-cluster address, so there is nothing to configure for it to reach the API. Set config.mcp.llamaCloudBaseUrl only if you need it to call a different endpoint; a public host there must use https.

Give it a hostname

MCP needs a hostname of its own — it answers on paths the web UI already uses, so it cannot share the main one. Point a second DNS name at the same ingress and set it as the public URL:

ingress:
  enabled: true
  host: cloud.your-company.example
  tlsSecretName: llamacloud-tls
  ingressClassName: nginx

config:
  mcp:
    enabled: true
    publicUrl: https://mcp.your-company.example

The chart adds an ingress rule sending that host to the MCP service. Two things it cannot do for you:

• mcp.your-company.example has to resolve to the same ingress as cloud.your-company.example.
• llamacloud-tls has to cover both names. One certificate serves both, so it needs a subject alternative name for each, or a wildcard.

The MCP rule shares the Ingress object with the web UI, so everything in ingress.annotations applies to it as well. Re-read any rewrite, auth or timeout annotation you set for the UI before assuming it suits MCP — an ingress controller’s default read timeout in particular governs how long a single MCP request may take.

Set publicUrl to a full URL including the scheme, and without a path — clients append their own (/mcp, /parse/mcp, and the rest). Wherever the chart derives a route from it, a value with no scheme is refused at render time rather than quietly producing no route. Once it is set, the web UI starts offering ready-made MCP client configuration, because it finally knows a URL your users’ agents can reach.

The rule is derived from publicUrl, so the chart routes any publicUrl host that differs from ingress.host. Two shapes leave it out of the way: a publicUrl on ingress.host, which it never routes because MCP answers on paths the web UI already owns, and ingress.enabled: false, where it renders no Ingress at all. In either case send what you route to the llamacloud-mcp service on port 80.

What you cannot do today is keep the chart’s Ingress enabled, advertise MCP on a hostname of its own, and route that hostname yourself — the chart adds its own rule for it, and two Ingresses claiming one host resolve in an order you do not control.

Authentication

Self-hosted MCP servers authenticate with a LlamaCloud API key, which users pass as a bearer token:

{
  "mcpServers": {
    "llamaparse": {
      "url": "https://mcp.your-company.example/mcp",
      "headers": { "Authorization": "Bearer ${LLAMA_CLOUD_API_KEY}" }
    }
  }
}

One tool behaves differently as a result. getUploadUrl hands back a pre-signed URL for uploading a local file, and it is not available to API key callers — it would leave a standing credential for anyone who reached that URL. Agents should call uploadFileByUrl instead, with a URL the server can reach. Everything else works the same.

Documents hosted inside your network

uploadFileByUrl refuses private and link-local addresses by default, which stops a caller using the server to reach things it should not. If the documents your users upload genuinely live on an internal host, allow it explicitly:

config:
  mcp:
    allowPrivateUploadHosts: true

Only turn this on if you are comfortable with callers naming internal addresses, since it is what the default protects against.

Check it is working

kubectl -n <your-namespace> get ingress
kubectl -n <your-namespace> get pods -l app.kubernetes.io/name=llamacloud-mcp

Then confirm the server is reachable at the hostname you configured:

curl -sS https://mcp.your-company.example/api/healthz

A pod that starts and an endpoint that answers do not prove a client can use it — connect an agent and call a tool. The MCP documentation covers client configuration and the full tool list, and applies to your deployment with your own hostname in place of mcp.llamaindex.ai.