MCP Servers¶

Model Context Protocol (MCP) servers let an Agent connect to external tools, data sources, and internal systems. Within its authorization scope, the Agent can query data, invoke tools, access system capabilities, or perform specific operations.

Unlike a Skill, an MCP service is closer to a tool gateway. Services that connect to production systems, customer data, or write-capable APIs require particular attention to permissions, data scope, and operational risk.

If you are not sure whether to use a Skill, an MCP server, or both, start with Skills and MCP: How to Choose.

Configuration Model¶

Obsy Agent Teams uses a "configure globally, enable per Agent, verify at runtime" model:

Step	Location	Description
1	Global configuration in Settings	Add, edit, or remove services available to the workspace, then inspect configuration and tool information.
2	MCP Servers in an Agent workspace	Enable the services needed by the current Agent and wait for runtime installation and activation.
3	Agent task	Describe the goal so the Agent can select an appropriate activated tool.

flowchart LR
  A[Configure a global MCP service] --> B[Enable it for an Agent]
  B --> C[Agent runtime installs and activates it]
  C --> D[Inspect actual tools]
  D --> E[Use them in a task]

Global configuration determines which services are available in the workspace; it does not expose them to every Agent automatically. A switch in an Agent workspace affects that Agent only.

Before You Start¶

Make sure that:

The MCP Server comes from a trusted source and provides configuration suitable for the runtime environment;
The target Agent host can reach the MCP Server, package registry, and related business systems;
A local stdio service has the required Node.js, Python, or other runtime dependencies;
A remote HTTP service has the required network, proxy, certificate, and authentication setup;
Your account can manage global MCP services and the target Agent;
The data scope and possible write operations exposed by the tools are understood.

Step 1: Manage Global MCP Servers¶

Select your avatar and open Agent Configuration > MCP Servers in Settings. This workspace-level capability pool lets administrators add, search, edit, or remove services and inspect available tool information. Whether a service is enabled for a particular Agent is controlled from that Agent's workspace.

Add a Service¶

Click Add MCP.
Select Form or Advanced JSON.
Enter the connection information provided by the MCP Server provider.
Save the configuration.
Review the configuration status and discovered tools on the service card.

Choose a Configuration Method¶

Method	When to use it	What to configure
Form	Recommended for a common single MCP Server.	Enter the name, connection type, and corresponding command or URL. Add arguments, environment variables, headers, a working directory, or a timeout when needed.
Advanced JSON	Use configuration copied from the provider or options that the form cannot represent.	Enter the JSON configuration supplied by the MCP Server provider.

The form supports STDIO, Streamable HTTP, and compatible SSE connections. For STDIO, enter the command required to start the service. For a remote connection, enter the service URL. The page displays fields for the selected connection type.

Complete the Form Fields¶

Every connection type requires these fields:

Field	Required	Description
Name	Yes	The display name of the MCP Server in the current workspace. Use a name that identifies its source or purpose so it is easy to search, enable, and troubleshoot.
Transport	Yes	The connection method supported by the MCP Server. Select the type specified in the provider's setup instructions.

For STDIO, the Agent starts a local process in its runtime environment and communicates with the MCP Server through standard input and output:

Field	Required	Description
Command	Yes	The executable used to start the MCP Server, such as `npx`, `node`, or `python`. It must be installed and executable in the Agent runtime environment.
Arguments	No	Enter the arguments passed to the command in execution order. Command options, package names, and script paths are commonly entered here, with one independent argument per row.
Environment variables	No	Provide configuration required when the process starts as key-value pairs. Variable names must be unique; include only variables required by this service.
Working directory	No	The directory from which the command starts. Set it when a configuration or script uses relative paths, and ensure the Agent runtime can access the directory.
Package name	No	Identifies the package associated with the MCP Server for display and recognition. It does not replace the command or arguments.
Timeout (seconds)	No	The maximum time to wait for the service to respond. If empty, the system default applies. Increase it when initialization or queries legitimately take longer.

For Streamable HTTP or SSE (compatible), the Agent connects to an already deployed MCP Server over the network:

Field	Required	Description
URL	Yes	The complete MCP Server address. For Streamable HTTP, enter its MCP endpoint. Select SSE only when the provider explicitly requires the compatible SSE connection, then enter that service address.
Headers	No	Add fixed key-value pairs required by the provider, such as authentication information, a tenant identifier, or other request headers. Header names are case-insensitive and must be unique.
Timeout (seconds)	No	The maximum time to wait for a connection or service response. If empty, the system default applies. Increase it when the network or service legitimately needs more processing time.

Credential security

Environment variables and headers become part of the MCP Server configuration. Include only information required for the connection, do not use credentials from an untrusted source, and do not copy the configuration to uncontrolled locations. Rotate or revoke a credential immediately if it is exposed.

Form and Advanced JSON edit the same configuration, and switching methods does not save automatically. The page retains unsubmitted content where possible. If the JSON contains multiple servers, a specialized connection type, or settings that the form cannot preserve, the page asks you to continue in Advanced JSON so information is not lost.

Follow the MCP Server provider's instructions. Do not guess commands, arguments, or endpoints to make a configuration pass validation. Use team-approved secret management instead of placing long-lived credentials where many users can view them.

Note

Form mode configures one MCP Server at a time. Before editing or removing a service, identify which Agents currently depend on it.

Inspect and Refresh Tools¶

A global service card shows configuration status and tool discovery results. Depending on the service, you can:

Expand the tool list to review names and descriptions;
Refresh the tool list for one remote MCP Server;
Select Refresh all to update remote MCP Servers in the workspace that support discovery;
Inspect discovery errors;
Edit configuration;
Remove the service.

The global page shows tools discovered from remote MCP Servers. It does not mean that a particular Agent can already use them. Enable the service for an Agent and verify its runtime status in that Agent's workspace. A local STDIO service runs in the Agent environment, so confirm its tools there after enabling it.

Discovering, failed discovery, not yet discovered, and no tools found are different states. During a refresh, the page may continue to show the last successfully discovered tools. If a refresh fails, the previous list remains visible with a warning that it may be outdated. Fix the connection or configuration and refresh again to confirm the current tools.

Step 2: Enable the Server for an Agent¶

A globally configured service is not enabled for every Agent:

Open the target Agent workspace.
Go to Configuration > MCP Servers.
Find the service and turn on its switch.
Wait for the resource to be saved, installed, and activated.
Expand runtime tools and confirm that the count, names, and descriptions are as expected.

Search matches the MCP server name, runtime tool name, and tool description, so you can locate a server from the capability you need.

Each switch action saves only that MCP service; it does not resubmit or lock every MCP configuration for the Agent. While the current service is saving, installing, waiting, or being removed, its switch is temporarily locked. Other services remain independent.

Enable services according to Agent responsibility and least privilege. A production troubleshooting Agent may need read-only query services; a cloud cost Agent may need billing services; a document organization Agent should not receive production tools.

Understand Runtime Status¶

The Agent workspace follows configuration from save through runtime availability:

State	Meaning	Recommendation
Saving or waiting for Agent	The desired configuration was submitted and is waiting for the Agent.	Keep the Agent online and wait for the state to advance.
Installing	The Agent is preparing dependencies or connecting to the service.	Avoid repeated switching; verify network and dependency installation access.
Active	Agent runtime has loaded the service.	Expand runtime tools and verify actual availability.
Removing	The service was disabled and runtime resources are being removed.	Wait before enabling it again.
Installation failed	A dependency, configuration, network, or connection check failed.	Inspect the error and troubleshooting ID, fix the cause, then reinstall.
Agent upgrade required	The runtime version does not support the required configuration synchronization.	Upgrade the Agent service, then retry.
Runtime synchronization paused	Synchronization is paused; previously reported tools do not prove that the current configuration is active.	Check Agent status and the page guidance before resuming.

The runtime tool section is collapsed by default. Its header shows the count actually reported by Agent runtime. Expand it to inspect components, transports, tool names, and descriptions. Disabling a service immediately hides its tools from the current availability list.

When a new configuration fails but a previous version is still serving tools, the page displays an explicit warning. Do not treat the new configuration as active until the error is fixed and reinstallation completes.

Step 3: Use MCP Tools in a Task¶

After activation, the Agent can select an MCP tool based on the task goal. You can also state which objects to query, which capability to use, and what output to return.

Start with a low-risk test:

Use the enabled read-only Kubernetes MCP service to list the five Pods with the most restarts in the test namespace.
Read data only. Return the object name, restart count, and recommended checks.

For production environments, customer data, permission changes, or write operations, define the exact scope, expected result, and actions requiring approval. Confirm that the Agent's access scope and behavioral boundaries match the task.

Best Practice: Connect and Validate an MCP Server¶

Start with one Agent, read-only tools, and a non-production scope. Expand usage only after validation:

Confirm the purpose and source: Obtain the configuration from the MCP Server provider's official instructions. Identify the data it accesses, the tools it exposes, and whether any tool can perform write operations.
Use least-privilege access: Prefer read-only credentials and limit access to a test environment or the business objects required for validation. Manage credentials using a team-approved method and do not share them with unrelated members.
Inspect tools in global configuration: After saving, review the discovery status and confirm that tool names and descriptions match expectations. Refresh the tool list after changing a remote service configuration.
Enable it only for the test Agent: Turn on the service in the target Agent workspace, wait until it becomes active, and inspect the tools reported by runtime. Tools discovered on the global page do not mean that the Agent can already use them.
Run a low-risk test task: State the target object, read-only requirement, and output format. Verify that the Agent selects the expected tool, returns the expected data, and explains when the tool is unavailable.
Expand only after validation: After confirming permissions, data quality, and runtime stability, use the service for production tasks or additional Agents. Keep human confirmation for write operations and define allowed and prohibited actions in Agent behavioral boundaries.

After changing configuration, service version, or credentials, repeat tool refresh, runtime verification, and the low-risk test. Do not rely on a previously successful tool list as proof that the current configuration is available.

Troubleshoot MCP Servers¶

Symptom	What to check
Global configuration cannot be saved	Follow the required-field message. In Advanced JSON, check the configuration structure, service name, and required command or URL.
Connection fails	Inspect error details and verify endpoint, network, proxy, certificate, and authentication.
Tool refresh fails	Verify the connection and authentication, then refresh again. If old tools remain visible, treat them only as the last successful result, not the current state.
The service is missing from the Agent workspace	Confirm that it still exists in the current workspace's global configuration, then reopen the Agent workspace and check again.
The switch remains in a waiting state	Confirm that the Agent is online and up to date, then review runtime logs and the troubleshooting ID.
Installation fails	Check the `stdio` command, dependencies, package registry, and host permissions, or remote HTTP connectivity.
The service is active but has no tools	Expand runtime tools and wait for the page to update automatically. Confirm that the MCP Server exposes tools and no component has failed; retry only when the page offers that action.
A task does not use the MCP tool	Confirm that the tool appears in the current Agent's runtime list and describe the target object and desired capability explicitly.

Recommendations¶

Enable only the MCP services directly related to the Agent's responsibility;
Prefer read-only or least-privilege credentials and restrict data and action scope in the target system;
Copy configuration from trusted sources and review package versions before upgrades;
Keep human approval for production writes and state prohibited actions in Agent behavioral boundaries;
After a change, verify activation from runtime status and the actual tool list;
Review failed, disabled, and unused services regularly and repair or remove them;
When a required service is unavailable, require the Agent to state the missing capability instead of drawing a definite conclusion from incomplete data.