---
updatedAt: 2026-04-08T20:33:38.000Z
agentTools:
projectIndex: https://docs.envia.com/llms.txt
---
# MCP Server
The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and APIs. Envia's MCP server exposes the complete Shipping, Queries, and Geocodes APIs as tools that AI agents can discover, understand, and call on your behalf. **Note:** The Geocodes API does not require authentication; the `envia_validate_address` tool can be used without an API key for address validation. Shipping and Queries tools still require your API key.
Instead of copying endpoints and crafting JSON payloads manually, you describe what you need in plain language — and the assistant handles everything for you.
## What you can do
With Envia's MCP server connected, you can ask your AI assistant things like:
* **Quote shipping rates** — "Get me DHL rates from Monterrey to CDMX for a 2.5 kg box"
* **Create shipping labels** — "Generate a FedEx Express label for this order"
* **Track packages** — "Where is tracking number 7072262094?"
* **Validate addresses** — "Is postal code 64060 valid in Mexico?"
* **Explore carriers** — "What carriers are available for domestic shipping in Mexico?"
* **Manage shipments** — "Cancel shipment 7072262094" or "Schedule a pickup for tomorrow"
## How it works
You type a request in plain language. Your AI assistant figures out which Envia API to call, builds the request, sends it, and returns the answer — all automatically.
```mermaid
sequenceDiagram
participant You as You (IDE)
participant Agent as AI Agent
participant MCP as Envia MCP Server
participant API as Envia APIs
You->>Agent: "Get DHL rates from MTY to CDMX"
Agent->>MCP: Discover available tools
MCP-->>Agent: Tool list (rate, generate, track, ...)
Agent->>MCP: Call rate tool with parameters
MCP->>API: POST /ship/rate/
API-->>MCP: Rate response
MCP-->>Agent: Formatted results
Agent-->>You: "DHL Express: $185.20 MXN, 2-3 days"
```
***
## Get started
Setting up the MCP server takes about 5 minutes. Follow these three steps:
### Step 1 — Get your API key
You need an Envia API key to authenticate. If you don't have one yet:
1. Go to **Desarrolladores → Acceso de API** in your [sandbox dashboard](https://shipping-test.envia.com/settings/developers) or [production dashboard](https://shipping.envia.com/settings/developers)
2. Copy your API token — you will paste it in the next step
**Don't have an account?** [Create a free sandbox account](https://accounts-sandbox.envia.com/signup) to get started. Sandbox mode lets you test everything without real charges.
### Step 2 — Choose your AI assistant
Pick the AI assistant you use. Each one requires a small configuration file where you paste your API key.
Open (or create) the Claude Desktop configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Paste the following and replace `your_api_key_here` with the token you copied in Step 1:
```json
{
"mcpServers": {
"envia": {
"command": "npx",
"args": ["@envia/envia-mcp@latest"],
"env": {
"ENVIA_API_KEY": "your_api_key_here"
}
}
}
}
```
Save the file and restart Claude Desktop.
Create a file called `.cursor/mcp.json` in your project root and paste:
```json
{
"mcpServers": {
"envia": {
"command": "npx",
"args": ["@envia/envia-mcp@latest"],
"env": {
"ENVIA_API_KEY": "your_api_key_here"
}
}
}
}
```
Replace `your_api_key_here` with the token you copied in Step 1.
Create a file called `.vscode/mcp.json` in your project root and paste:
```json
{
"servers": {
"envia": {
"type": "stdio",
"command": "npx",
"args": ["@envia/envia-mcp@latest"],
"env": {
"ENVIA_API_KEY": "your_api_key_here"
}
}
}
}
```
Replace `your_api_key_here` with the token you copied in Step 1. Requires GitHub Copilot with agent mode enabled.
**What does this configuration do?** It tells your AI assistant to launch the Envia MCP server (via `npx`) as a local process on your computer. You don't need to install anything separately, open any ports, or deploy a server — `npx` downloads and runs it automatically. The `@latest` tag ensures you always get the most recent version.
### Step 3 — Try it out
Open your AI assistant and try one of these prompts:
* "What carriers are available for domestic shipping in Mexico?"
* "Validate postal code 64000 in Mexico"
* "Get DHL rates from Monterrey to Mexico City for a 2 kg box"
If the assistant responds with real data, you're all set.
***
## Configuration reference
### Environment variables
| Variable | Required | Default | Description |
| ------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENVIA_API_KEY` | Yes | — | Your Envia API token from **Desarrolladores → Acceso de API** ([sandbox](https://shipping-test.envia.com/settings/developers) \| [production](https://shipping.envia.com/settings/developers)) |
| `ENVIA_ENVIRONMENT` | No | `sandbox` | `sandbox` for testing or `production` for live shipments |
**Sandbox vs Production.** By default, the server connects to sandbox — your shipments are simulated and no real charges are made. When you are ready to go live, add `"ENVIA_ENVIRONMENT": "production"` to the `env` block in your configuration.
### Available tools
The MCP server registers 10 tools that cover the complete shipping lifecycle:
| Tool | What it does | API |
| --------------------------------- | ----------------------------------------------------------- | -------- |
| `envia_validate_address` | Validate postal codes and look up cities (no auth required) | Geocodes |
| `envia_list_carriers` | List available carriers and services for a country | Queries |
| `envia_get_shipping_rates` | Compare rates across multiple carriers for a route | Shipping |
| `envia_create_label` | Purchase a shipping label (charges your balance) | Shipping |
| `envia_track_package` | Track one or more shipments by tracking number | Shipping |
| `envia_cancel_shipment` | Void a label and reclaim your balance | Shipping |
| `envia_schedule_pickup` | Schedule a carrier pickup at the origin address | Shipping |
| `envia_get_shipment_history` | List all shipments created in a given month | Queries |
| `envia_classify_hscode` | Classify a product into an HS code for customs | Shipping |
| `envia_create_commercial_invoice` | Generate a customs invoice PDF for international shipments | Shipping |
You don't need to memorize these — your AI assistant discovers them automatically and picks the right one based on what you ask.
***
## See it in action
These examples show what a real conversation with the AI assistant looks like.
### Domestic shipment (Mexico)
```
You: Ship a 2 kg box (30×20×15 cm) from postal code 64000 in Monterrey
to 03100 in Mexico City. Compare DHL and Estafeta rates.
AI: [calls envia_validate_address for both postal codes]
[calls envia_get_shipping_rates with carriers: dhl,estafeta]
Here are your options:
DHL Economy: $185.20 MXN — 3-5 business days
Estafeta Express: $210.00 MXN — 1-2 business days
Would you like me to create a label with one of these?
You: Yes, go with DHL Economy.
AI: [calls envia_create_label]
Label created!
Tracking: 7520610403
Label PDF: https://...
Price: $185.20 MXN
```
### International customs classification
```
You: I need to ship handmade ceramic mugs from Mexico to the US.
What HS code should I use?
AI: [calls envia_classify_hscode]
Recommended HS code: 6912.00 — Ceramic tableware
This code is required for customs when creating an international label.
```
***
## Supported AI assistants
Envia's MCP server works with any AI assistant that supports the Model Context Protocol:
Anthropic's desktop app with native MCP support. Recommended for the best experience.
AI-native code editor with built-in MCP client. Ideal for developers building integrations.
GitHub Copilot in VS Code supports MCP servers in agent mode.
## What's next?
Full request/response examples for every shipping step — rates, labels, tracking, and more.
End-to-end walkthrough covering all three APIs from address validation to production.
How to generate API keys and authenticate requests across all three Envia APIs.
**Why MCP?**
MCP is becoming the standard way for AI agents to interact with APIs. Companies like Stripe, Cloudflare, and Shopify already publish MCP servers. By supporting MCP, Envia enables developers to build shipping features faster using AI-assisted workflows — without leaving their editor.