JSON-RPC 2.0 and MCP Server Testing

Overview

Shift-Left Studio tests JSON-RPC 2.0 services and Model Context Protocol (MCP) servers alongside your REST, SOAP and GraphQL APIs. An MCP server is a JSON-RPC 2.0 server with a fixed set of methods, so the same capability covers both.

JSON-RPC behaves differently from REST in one important way: a failed call usually comes back with HTTP 200. The transport succeeded; the operation did not, and the failure is described inside the response body. A test that only checks the status code will pass on a call that failed. Studio therefore gives JSON-RPC its own assertions that look inside the response, and generated tests use them automatically.

You can bring JSON-RPC services into a project from an OpenRPC document, or connect to a live MCP server and choose which of its tools to test. Each method or tool becomes its own endpoint, with generated positive and negative tests.

Key concepts

Before you begin

• Your licence must be Trial or Enterprise. On other editions the JSON-RPC options do not appear in the import dialog.
• You need permission to import APIs into the project.
• For an MCP server: its Streamable HTTP address (for example https://example.com/mcp) and, if it requires sign-in, a bearer token.
• For a JSON-RPC service: an OpenRPC document (.json), or a URL to one.
• A project environment whose base URL points at the service's origin. JSON-RPC runs over HTTP, so, like REST, it needs one.

Step 1 — Import an OpenRPC document

1. In the project tree, open the import dialog (Import API to Project, or Import API to Feature when a feature is selected).
2. Set API Type: to JSON-RPC / MCP.
3. Under Import Method, choose Upload File and select your OpenRPC .json file, or use URL import with the document's address.
4. Under Check before importing, click Preview methods to see the methods the document declares before anything is created.
5. Complete the import.

Each method in the document becomes one endpoint. Its parameter schema drives generation the same way a REST request body does, and any documented error codes are stored for negative tests.

Tip: Most internal JSON-RPC services have no published OpenRPC document. A plain method list also imports: a JSON file containing the HTTP path and the method names, for example { "httpPath": "/rpc", "methods": ["getBalance", "transfer"] }.

Step 2 — Discover and import an MCP server

1. Open the import dialog as above.
2. Under Import Method, click MCP Server.
3. Enter the MCP server URL.
4. If the server requires sign-in, enter its bearer token in Access token (only if the server needs one). Leave it empty otherwise.
5. Click Connect and list tools. Studio performs the real MCP handshake and lists the server's tools. Nothing is written yet.
6. Review the Connected summary (Server and Tools). If the server lists more tools than could be read, a note says the list may be incomplete.
7. Under Choose what to test, review the tools. Each is marked:
   • Safe to run — the server declares the tool read-only. These start ticked.
   • May change data — the tool does not declare itself read-only. These start unticked, because a generated happy-path test really runs the tool against your server.
8. Tick or untick tools, then click Import N tools.

Each selected tool becomes one endpoint. The tool's own input schema becomes the schema for its arguments, so generated tests exercise the tool's real parameters. Re-importing the same server later compares against what already exists instead of duplicating it. The project's base URL is filled in from the server address when it is not already set.

Important: The access token entered here is used to discover the server and is not stored on the endpoints. For runs against a server that requires sign-in, set the endpoint's Auth token reference (see Step 3).

Step 3 — Review and adjust an endpoint

Open an imported JSON-RPC endpoint to see or edit its settings:

Note: If you paste a complete JSON-RPC request (with jsonrpc, id and method) into a test body — for example, one copied from your logs — Studio accepts it and uses only the params.

Step 4 — Generate tests

Generate tests for JSON-RPC endpoints the same way as for any other endpoint. Generated tests include:

For MCP tools marked May change data, only import them if you are prepared for generated happy-path tests to act on the server.

Step 5 — Run the tests

1. Make sure the environment you run against has a base URL pointing at the service's origin (for example https://api.example.com). Studio appends the endpoint's HTTP path.
2. Run a test, a test run pack or a workflow as usual. JSON-RPC tests can be steps in workflows.
3. For MCP servers, Studio automatically opens a session, makes the call within it, and closes the session afterwards. If the server replies as an event stream instead of plain JSON, Studio unwraps it so the assertions see the same reply either way.

The run result shows a plain-language verdict instead of a bare HTTP status, because a green "200" would be misleading:

Assertion results also read in plain words, such as Rejected for the expected reason or Rejected, but for a different reason than expected.

Note: You can run JSON-RPC tests on the Engine (server) or the Agent (local runner). On the Agent, only env:NAME token references resolve; a key: or secretref: reference fails with a message naming it. Use the Engine for those.

Assertion reference

All JSON-RPC assertions are in the JSON-RPC category of the assertion picker.

Field checks inside the result use the usual field assertions — for example, a field-equals check on result.balance. Dynamic tokens such as {{row.EXPECTED_CODE}} work in these assertions as in any other.

Standard JSON-RPC 2.0 error codes: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error.

Current limitations

• Batch requests (an array of calls in one request) are not supported. A batch body is rejected with a message asking you to split it into individual tests. A plain array of values is still accepted as positional params.
• MCP over stdio is not supported; only Streamable HTTP.
• MCP resources and prompts are not modelled; tools only.
• MCP OAuth sign-in is not supported; bearer tokens only.
• Studio has been verified against the official MCP reference server and a standard JSON-RPC 2.0 library. It has not been verified against every vendor's server; if yours behaves differently, contact support.

Troubleshooting

Best practices

• Never rely on a status check alone for JSON-RPC. Every test should include at least one JSON-RPC assertion.
• For MCP, pair MCP: Tool Call Succeeded with MCP: Tool Output Contains to check what the tool actually returned.
• Keep tools marked May change data unticked unless you are testing against a disposable environment.
• Record documented error codes on each endpoint so negative tests assert the right code.
• If you created JSON-RPC tests in an older release, regenerate them to pick up the current negative-test assertions.

Related articles

• Test run
• Environments
• Project settings: environments and auth
• WebSocket-RPC Testing
• Testing Server-Sent Events (Streaming) Responses

Automating this

Named access keys for JSON-RPC endpoints (used as key:NAME in Auth token reference) can be saved with POST /api/jsonrpc/keys and listed with GET /api/jsonrpc/keys. The list returns key names only, never the credential. Saving under an existing name replaces the credential without breaking endpoints that reference it.

For administrators (self-hosted installations)