API reference

One API key. Every tool your agent needs

Edgevana ComputeAgent over MCP and A2A: your agent finds, prices and launches NVIDIA GPUs, and every launch is previewed for your approval first.

13 tools
MCP 2025-03-26 to 2025-11-25
A2A v0.3
JSON-RPC 2.0
Streamable HTTP

Get an API key Quickstart

At a glance

MCPhttps://mcp.edgevana.com/mcp

HeaderX-API-Key: edgv_...

Agent CardEdgevana Edge AI Infrastructure, v1.13.0

Endpoints and versions

Four addresses, one key. MCP for IDEs and agent apps; A2A for agents that read the Agent Card first.

MCPhttps://mcp.edgevana.com/mcpModel Context Protocol 2025-03-26 to 2025-11-25, Streamable HTTP
A2A JSON-RPChttps://mcp.edgevana.com/a2a/jsonrpcA2A v0.3 over JSON-RPC 2.0
A2A RESThttps://mcp.edgevana.com/a2a/restA2A v0.3 over HTTP and JSON
Agent Cardhttps://edgevana.com/.well-known/agent-card.jsonVersion 1.13.0, protocol 0.3.0

curl https://edgevana.com/.well-known/agent-card.json1curl https://edgevana.com/.well-known/agent-card.json

Authentication

One key in either header.

Your key starts with edgv_. Create it on nodes.edgevana.com/profile/api-keys and send it in either header:

X-API-Key: edgv_...
Authorization: Bearer edgv_...

Key scopes, rotation and spending limits per key are being written up.

curl -X POST https://mcp.edgevana.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: edgv_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'1curl -X POST https://mcp.edgevana.com/mcp \2  -H "Content-Type: application/json" \3  -H "Accept: application/json, text/event-stream" \4  -H "X-API-Key: edgv_..." \5  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

What an agent can do

Agents launch hourly GPUs end to end. Bare metal and CPU servers can be found and priced, not launched.

	Search	Price	Launch	Terminate
Hourly GPU	Yes	Yes	Preview, then confirm	Destroyed at once
Reserved GPU	Yes	Yes	Request, no charge	Immediately only
Bare metal	Yes	Yes	Not from the API	—
CPU servers	Yes	Yes	Not from the API	—

Approvals and limits

What keeps an agent from spending money nobody approved.

Every launch is previewed first: the preview returns the hourly price and an approval object, and creates nothing.
A confirm sends the approval object unchanged with a unique idempotency_key; a confirm without a deposit quote is refused.
If the approved offer is taken by the time you confirm, an equivalent offer at the same site may be launched instead, never above the approved hourly price or deposit; a higher price is refused. The approved deposit is the ceiling.
If the offer was just taken, the preview may offer an equivalent one (same GPU, possibly another site) in substituted: show substituted.note, and confirm with substituted.offer_id and substituted.site.
A retry with the same idempotency_key returns the first result while the server holds the record (it resets when the server restarts).
The deposit for an hourly GPU depends on its hourly price and is shown in the launch preview. It is non-refundable and comes back as account credit against usage.
Without an ssh_key an instance is billed but not provisioned.
ports: up to 16, from 1 to 65535, never 22. onstart: up to 4096 bytes, runs as root, stored in plain text. disk_gb: within disk_options, fixed after launch.
Hourly GPU instances are destroyed immediately. Other instances can only be destroyed with when: Immediately for now; EndOfTerm is refused.

{
  "tool": "launch_instance",
  "args": {
    "offer_id": "52708889",
    "site": "Seoul, South Korea",
    "ssh_key": "ssh-ed25519 AAAA...",
    "confirm": true,
    "approved": { "hourly_cents": 89, "deposit_due_cents": 2500 },
    "idempotency_key": "00000000-0000-4000-8000-000000000001"
  }
}1{2  "tool": "launch_instance",3  "args": {4    "offer_id": "52708889",5    "site": "Seoul, South Korea",6    "ssh_key": "ssh-ed25519 AAAA...",7    "confirm": true,8    "approved": { "hourly_cents": 89, "deposit_due_cents": 2500 },9    "idempotency_key": "00000000-0000-4000-8000-000000000001"10  }11}

Quickstart

Five calls from an offer to a running server and back.

Search

Pick an offer with launch_status "available"; note its offer_id and one of its hourly_sites.

{
  "tool": "search_servers",
  "args": { "server_type": "gpu", "query": "H100", "launchable_only": true, "sort": "price" }
}1{2  "tool": "search_servers",3  "args": { "server_type": "gpu", "query": "H100", "launchable_only": true, "sort": "price" }4}

Preview the launch

Returns the hourly price, an approval object and the deposit due today. Nothing is created: show it to the user. If approval.deposit_due_cents is null, run the preview again.

{
  "tool": "launch_instance",
  "args": { "offer_id": "52708889", "site": "Seoul, South Korea", "ssh_key": "ssh-ed25519 AAAA..." }
}1{2  "tool": "launch_instance",3  "args": { "offer_id": "52708889", "site": "Seoul, South Korea", "ssh_key": "ssh-ed25519 AAAA..." }4}

Confirm

After the user approves: the same arguments (or the substituted offer_id and site, if the preview offered a replacement), confirm: true, the approval object unchanged and a unique idempotency_key.

{
  "tool": "launch_instance",
  "args": {
    "offer_id": "52708889",
    "site": "Seoul, South Korea",
    "ssh_key": "ssh-ed25519 AAAA...",
    "confirm": true,
    "approved": { "hourly_cents": 89, "deposit_due_cents": 2500 },
    "idempotency_key": "00000000-0000-4000-8000-000000000001"
  }
}1{2  "tool": "launch_instance",3  "args": {4    "offer_id": "52708889",5    "site": "Seoul, South Korea",6    "ssh_key": "ssh-ed25519 AAAA...",7    "confirm": true,8    "approved": { "hourly_cents": 89, "deposit_due_cents": 2500 },9    "idempotency_key": "00000000-0000-4000-8000-000000000001"10  }11}

Monitor

Read connection.status until it is ready; then connection.ports lists the mapped ports. Check connection.ssh before reading its host, port and user.

{
  "tool": "get_instance",
  "args": { "instance_id": "example-instance-id" }
}1{2  "tool": "get_instance",3  "args": { "instance_id": "example-instance-id" }4}

Destroy

Call once without confirm for a preview, then again with confirm: true. Hourly GPU instances are destroyed immediately.

{
  "tool": "terminate_instance",
  "args": { "instance_id": "example-instance-id", "confirm": true }
}1{2  "tool": "terminate_instance",3  "args": { "instance_id": "example-instance-id", "confirm": true }4}

Tools

13 tools in three families. Every call that spends or destroys is previewed first.

Discover

Find servers, specs, locations, stock and prices. Read only.

search_servers

Read only

Search GPU and bare-metal offers by price, VRAM, GPU count and site.

16 parameters, all optional

server_type
query
region
site
launchable_only
max_price_hourly
min_vram_gb
min_gpus
min_direct_ports
min_reliability
min_ram_gb
min_cores
sort
detail_sku
offset
limit

{
  "tool": "search_servers",
  "args": {
    "server_type": "gpu",
    "query": "H100",
    "launchable_only": true,
    "sort": "price",
    "limit": 10
  }
}1{2  "tool": "search_servers",3  "args": {4    "server_type": "gpu",5    "query": "H100",6    "launchable_only": true,7    "sort": "price",8    "limit": 109  }10}

get_server_specs

Read only

Hardware specs for a server SKU.

1 parameter, optional

{
  "tool": "get_server_specs",
  "args": {
    "sku": "BM-9254-384G-25G"
  }
}1{2  "tool": "get_server_specs",3  "args": {4    "sku": "BM-9254-384G-25G"5  }6}

get_locations

Read only

Edgevana data center locations, by country or city.

2 parameters, all optional

country
city

{
  "tool": "get_locations",
  "args": {
    "country": "United States"
  }
}1{2  "tool": "get_locations",3  "args": {4    "country": "United States"5  }6}

check_availability

Read only

Live stock for GPU and bare-metal servers by site, type or SKU.

4 parameters, all optional

site
server_type
sku
limit

{
  "tool": "check_availability",
  "args": {
    "server_type": "gpu",
    "site": "Chicago"
  }
}1{2  "tool": "check_availability",3  "args": {4    "server_type": "gpu",5    "site": "Chicago"6  }7}

get_pricing

Read only

Prices in USD for GPU and bare-metal servers, with the count available.

5 parameters, all optional

server_type
item_id
search
include_locations
limit

{
  "tool": "get_pricing",
  "args": {
    "server_type": "gpu",
    "search": "H100",
    "limit": 10
  }
}1{2  "tool": "get_pricing",3  "args": {4    "server_type": "gpu",5    "search": "H100",6    "limit": 107  }8}

compare_to_cloud

Read only

Edgevana beside AWS, GCP and Azure for a workload type.

2 parameters, all optional

workload_type
cloud_provider

{
  "tool": "compare_to_cloud",
  "args": {
    "workload_type": "ai_inference",
    "cloud_provider": "aws"
  }
}1{2  "tool": "compare_to_cloud",3  "args": {4    "workload_type": "ai_inference",5    "cloud_provider": "aws"6  }7}

get_platform_info

Read only

The platform, its capabilities and architecture.

1 parameter, optional

topic

{
  "tool": "get_platform_info",
  "args": {
    "topic": "compute"
  }
}1{2  "tool": "get_platform_info",3  "args": {4    "topic": "compute"5  }6}

Provision

Launch an hourly GPU or request reserved capacity, each previewed before it is confirmed.

launch_instance

Preview, then confirm (spends money)

Launch an hourly GPU instance from an offer: a preview first, then the launch once confirmed.

12 parameters, 4 required

offer_idrequired
siterequired
ssh_key
custom_name
disk_gb
ports
onstart
payment_source_id
coupon_ids
confirm
approvedrequired when confirm: true
idempotency_keyrequired when confirm: true

{
  "tool": "launch_instance",
  "args": {
    "offer_id": "52708889",
    "site": "Seoul, South Korea",
    "ssh_key": "ssh-ed25519 AAAA..."
  }
}1{2  "tool": "launch_instance",3  "args": {4    "offer_id": "52708889",5    "site": "Seoul, South Korea",6    "ssh_key": "ssh-ed25519 AAAA..."7  }8}

request_reserved_instance

Preview, then confirm (no charge)

Send a request for a reserved GPU offer to Edgevana sales. Nothing is ordered or charged.

9 parameters, 4 required

offer_idrequired
siterequired
emailrequired
first_namerequired
last_name
quantity
term_months
notes
confirm

{
  "tool": "request_reserved_instance",
  "args": {
    "offer_id": "52700000",
    "site": "Dallas, TX",
    "email": "[email protected]",
    "first_name": "Alex",
    "quantity": 8,
    "term_months": 12
  }
}1{2  "tool": "request_reserved_instance",3  "args": {4    "offer_id": "52700000",5    "site": "Dallas, TX",6    "email": "[email protected]",7    "first_name": "Alex",8    "quantity": 8,9    "term_months": 1210  }11}

Manage

List, read, change and terminate your instances.

list_instances

Read only

The instances on your account, each with its connection.

2 parameters, all optional

limit
offset

{
  "tool": "list_instances",
  "args": {
    "limit": 10
  }
}1{2  "tool": "list_instances",3  "args": {4    "limit": 105  }6}

get_instance

Read only

Status, specs, site and billing for one instance.

1 parameter, required

instance_idrequired

{
  "tool": "get_instance",
  "args": {
    "instance_id": "example-instance-id"
  }
}1{2  "tool": "get_instance",3  "args": {4    "instance_id": "example-instance-id"5  }6}

update_instance

Changes settings, no charge

Change an instance’s SSH key, cluster, deployment type or name.

5 parameters, 1 required

instance_idrequired
ssh_key
cluster
deployment_type
custom_name

{
  "tool": "update_instance",
  "args": {
    "instance_id": "example-instance-id",
    "custom_name": "inference-1"
  }
}1{2  "tool": "update_instance",3  "args": {4    "instance_id": "example-instance-id",5    "custom_name": "inference-1"6  }7}

terminate_instance

Preview, then confirm (destructive)

Destroy an instance: a preview first, then confirm.

4 parameters, 1 required

instance_idrequired
when
cancel_reason
confirm

{
  "tool": "terminate_instance",
  "args": {
    "instance_id": "example-instance-id"
  }
}1{2  "tool": "terminate_instance",3  "args": {4    "instance_id": "example-instance-id"5  }6}

Objects

What the calls return that an agent reads.

connection

How to reach an instance, on get_instance.

status: ready, provisioning, failed, destroying (cancelled, not yet confirmed gone) or destroyed
public_ip: A string, or null while the instance is not ready (it can stay null when ready)
ssh: null, or host, port and user
ports: The mapped ports: internal, proto, external, ip; [] while not ready
destroyed_at: When the instance was destroyed

approval

What the user approves, returned by a launch preview and sent back unchanged on confirm.

hourly_cents: The hourly price in cents
deposit_due_cents: The deposit due today; null means run the preview again

offer

A server you can launch or price, from search_servers.

offer_id: Pass it to launch_instance or request_reserved_instance
hourly_sites: The sites it launches in by the hour
launch_status: "available" when it can be launched now; launch_note says why not
available_count: How many are free
offer_kind: The kind of offer
disk_options.included_gb: The disk included in the price
host.direct_port_count: Direct ports on the host

The server publishes each tool’s input schema through tools/list; full response schemas are not published yet.

Connect a client

Paste one of these with your own key.

The Agent Card (Edgevana Edge AI Infrastructure, version 1.13.0) lists nine A2A skills, each covering one or more of the tools:

search-servers
get-pricing
check-availability
get-locations
get-server-specs
compare-cloud
provision-instance
manage-instances
platform-info

{
  "mcpServers": {
    "edgevana": {
      "url": "https://mcp.edgevana.com/mcp",
      "headers": { "X-API-Key": "<your-edgv_...-key>" }
    }
  }
}1{2  "mcpServers": {3    "edgevana": {4      "url": "https://mcp.edgevana.com/mcp",5      "headers": { "X-API-Key": "<your-edgv_...-key>" }6    }7  }8}

Errors and limits

search_servers and list_instances page with offset and limit.
ERROR_PORTS_UNMAPPED: the host could not map the requested ports before the port checks timed out. The service tries to destroy the instance; check connection.status before another launch.
A confirm without a deposit quote, or above the approved hourly price, is refused.

The error format, the full list of codes, rate limits, key scopes and rotation, and the versioning policy are being written up.

Coming soon

Promised elsewhere on the site; shown here as coming, never as available.

Not yet publishedREST APIResource endpoints for compute, network and billing.
Not yet publishedOpenAPIA machine-readable description of the REST API.
Not yet publishedSDKsClient libraries for common languages.
Not yet publishedCLIThe same operations from a terminal.
Not yet publishedTerraform providerInfrastructure as code for Edgevana resources.

Talk to an infrastructure engineer

Live chat, email answered within 2 hours in business hours, and a dedicated account manager for enterprise teams.