Manage MCP services

The mcp service command group manages AgentKit MCP services. An MCP service deploys a containerized MCP server as an AgentKit cloud resource with network and authentication settings. The current release supports listing, inspecting, creating, and deleting services. Creation supports only the custom-private backend and the MCP protocol. Sign in to the target provider with permissions to manage MCP services, pull images, and use the selected gateway. Image URLs below illustrate the format; replace them with uploaded, pullable images. For BytePlus, use --provider byteplus with its region and registry

Creating a service deploys a container and can enable billable monitoring and logs. The default --network public exposes a public endpoint. With inbound authentication configured, still check that the tools are appropriate for the intended callers

Command overview

Command	Description
`agentkit mcp service list`	List MCP services
`agentkit mcp service show <service>`	Show an MCP service by name or ID
`agentkit mcp service create`	Create an MCP service from a container image
`agentkit mcp service delete <service>`	Delete an MCP service

mcp service list

List MCP services in a project. When no region is specified, the CLI detects the region automatically. Use --json to return raw JSON for scripts.

Flag	Description	Default
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`-p, --project <name>`	AgentKit project name.	`default`
`--json`	Output raw JSON.	`false`
`--gateway-instance-id <id>`	Filter by exclusive gateway instance ID	—

agentkit mcp service list --project default

mcp service show

Show an MCP service’s status, backend type, protocol, access path, project, and tags. <service> can be a service name or ID. A name must be unique within the project.

Flag/argument	Description	Default
`<service>`	MCP service name or ID. Required.	—
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`-p, --project <name>`	AgentKit project name, used when resolving by name.	`default`
`--json`	Output raw JSON, including network, authentication, and backend configuration.	`false`

agentkit mcp service show customer-tools

mcp service create

Create an MCP service from a container image. Before starting, prepare an image that AgentKit can pull and make sure its startup command runs the MCP server. On success, the command prints the service name and ID.

Only the custom-private backend and mcp protocol are currently available. --backend-type recognizes reserved values for other backends, but creation rejects backends that are not yet supported.

Flag	Description	Default
`--name <name>`	MCP service name. Required.	—
`--description <text>`	Service description.	—
`-p, --project <name>`	AgentKit project name.	`default`
`-r, --region <region>`	Region for the selected cloud provider.	environment setting
`--client-token <token>`	Client token used to make repeated requests idempotent.	—
`--backend-type <type>`	Backend type: `custom-private`, `custom-public`, `function`, `domain`, `ecs`, or `vke`. Only `custom-private` is currently supported.	`custom-private`
`--image-url <url>`	Container image URL for the `custom-private` backend. Required.	—
`--command <cmd>`	Container startup command.	`./run.sh`
`--env <key=value>`	Container environment variable. Repeatable; keys must be unique.	empty
`--enable-apmplus`	Enable APMPlus and the logging service.	`true`
`--no-enable-apmplus`	Disable APMPlus and the logging service.	—
`--network <mode>`	Network mode: `public`, `private`, or `hybrid`.	`public`
`--vpc-id <id>`	VPC ID for private or hybrid networking.	—
`--subnet-id <id>`	Subnet ID for private or hybrid networking.	—
`--inbound-auth <type>`	Inbound authentication: `api-key` or `custom-jwt`.	`api-key`
`--inbound-api-key-name <name>`	Inbound API key name. Required with `api-key`; repeat 1–5 times.	empty
`--inbound-api-key <key>`	Inbound API key value. Optional; if provided, supply one for every name.	empty
`--inbound-api-key-param <name>`	Header used to pass the inbound API key.	`Authorization`
`--inbound-discovery-url <url>`	OIDC discovery URL for `custom-jwt`.	—
`--inbound-allowed-client <id>`	Client ID allowed by `custom-jwt`. Required and repeatable.	empty
`--outbound-credential-provider <name>`	Credential provider for outbound OAuth2 user federation.	—
`--tag <key=value>`	Custom tag. Repeatable; keys must be unique.	empty
`--path <path>`	MCP service access path.	`/mcp`
`--protocol <type>`	Protocol type; only `mcp` is currently supported.	`mcp`
`--gateway-mode <mode>`	Gateway mode: `Shared` or `Exclusive`	`shared`
`--gateway-instance-id <id>`	Exclusive gateway instance ID, required in Exclusive mode	—
`--backend-access-type <type>`	Exclusive gateway backend access: `Public` or `Private`	Server default

The following example creates a public service with inbound API key authentication:

agentkit mcp service create \
  --name customer-tools \
  --image-url cr-cn-beijing.volces.com/agentkit/customer-tools:latest \
  --inbound-api-key-name primary-key \
  --env LOG_LEVEL=INFO \
  --tag team=customer-service

Configure networking

The public mode cannot be combined with a VPC or subnet. Both private and hybrid require --vpc-id and --subnet-id; hybrid enables public and private access.

agentkit mcp service create \
  --name internal-tools \
  --image-url cr-cn-beijing.volces.com/agentkit/internal-tools:latest \
  --network private \
  --vpc-id vpc-xxxxxxxx \
  --subnet-id subnet-xxxxxxxx \
  --inbound-api-key-name internal-key

Configure custom JWT

With custom-jwt, provide an OIDC discovery URL and at least one allowed client ID. Do not pass API key flags in the same command.

agentkit mcp service create \
  --name jwt-protected-tools \
  --image-url cr-cn-beijing.volces.com/agentkit/jwt-tools:latest \
  --inbound-auth custom-jwt \
  --inbound-discovery-url https://identity.example.com/.well-known/openid-configuration \
  --inbound-allowed-client web-client

mcp service delete

Deleting an MCP service cannot be undone. Verify the name or ID, project, and region before continuing. In automation, --yes skips the confirmation prompt.

Flag/argument	Description	Default
`<service>`	MCP service name or ID. Required.	—
`-r, --region <region>`	Region for the selected cloud provider.	auto-detect
`-p, --project <name>`	AgentKit project name, used when resolving by name.	`default`
`-y, --yes`	Skip the deletion confirmation.	`false`

agentkit mcp service delete customer-tools

Exclusive gateways

Exclusive mode requires an existing gateway instance and inherits its network. Do not combine it with private or hybrid --network, --vpc-id, or --subnet-id. Shared mode rejects --gateway-instance-id and --backend-access-type

agentkit mcp service list --gateway-instance-id gateway-example --json

This example creates a service through an existing exclusive gateway with private backend access. Replace the image URL and gateway ID with your resources before running it. Creating a service can incur cloud charges

agentkit mcp service create \
  --name internal-tools \
  --image-url cr-cn-beijing.volces.com/agentkit/internal-tools:latest \
  --inbound-api-key-name primary-key \
  --gateway-mode Exclusive \
  --gateway-instance-id gateway-example \
  --backend-access-type Private

After creation, run agentkit mcp service show internal-tools to verify gateway and backend access settings After the create request succeeds, use mcp service show to inspect state and the access address, then verify tool discovery and a call from the client. If a ready service rejects calls, distinguish its inbound API key/JWT from outbound credentials used by tools to access external systems

Getting Started

AI-Friendly

Command reference

Command overview

mcp service list

mcp service show

mcp service create

Configure networking

Configure custom JWT

mcp service delete

Exclusive gateways

​Command overview

​mcp service list

​mcp service show

​mcp service create

​Configure networking

​Configure custom JWT

​mcp service delete

​Exclusive gateways

Command overview

mcp service list

mcp service show

mcp service create

Configure networking

Configure custom JWT

mcp service delete

Exclusive gateways