mcp-code-exec-python
If you are the rightful owner of mcp-code-exec-python and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This document provides a comprehensive guide on deploying and testing a Model Context Protocol (MCP) server using Heroku, specifically for Python code execution.
Heroku MCP Code Execution - Python
- Heroku MCP Code Execution - Python
Automatic Deployment
Manual Deployment
Set Required Environment Variables from Heroku CLI
Instead of manually setting each variable, use the Heroku CLI to pull the correct values.
export APP_NAME=<your-heroku-app-name>
heroku create $APP_NAME
heroku buildpacks:set heroku/python -a $APP_NAME
# set a private API key that you create, for example:
heroku config:set API_KEY=$(openssl rand -hex 32) -a $APP_NAME
heroku config:set STDIO_MODE_ONLY=<true/false> -a $APP_NAME
# set the remote server type (module) that your web process will use (only relevant for web deployments)
heroku config:set REMOTE_SERVER_TRANSPORT_MODULE=<streamable_http_server/sse_server>
Note: we recommend setting STDIO_MODE_ONLY to true for security and code execution isolation security in non-dev environments.
If you only want local & deployed STDIO capabilities (no SSE server), run:
heroku ps:scale web=0 -a $APP_NAME
If you do want a deployed SSE server, run:
heroku ps:scale web=1 -a $APP_NAME
heroku config:set WEB_CONCURRENCY=1 -a $APP_NAME
Optionally, put these config variables into a local .env file for local development:
heroku config -a $APP_NAME --shell | tee .env > /dev/null
Next, connect your app to your git repo:
heroku git:remote -a $APP_NAME
And deploy!
git push heroku main
View logs with:
heroku logs --tail -a $APP_NAME
Local Testing
One-time packages installation:
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt
Local Streamable HTTP, SSE
If you're testing (stateless) Streamable HTTP OR SSE, in one terminal pane you'll need to start the server:
source venv/bin/activate
export API_KEY=$(heroku config:get API_KEY -a $APP_NAME)
# Either run src.streamable_http_server or src.sse_server, here:
uvicorn src.streamable_http_server:app --reload
Running with --reload is optional, but great for local development
Next, in a new pane, you can try running some queries against your server:
Local Streamable HTTP, SSE - Example Requests
First run:
export API_KEY=$(heroku config:get API_KEY -a $APP_NAME)
In the following commands, use either example_clients/streamable_http_client.py if you ran the streamable HTTP server above, or example_clients/sse_client.py if you're running the SSE server.
List tools:
python example_clients/streamable_http_client.py mcp list_tools | jq
Example tool call request:
NOTE: this will intentionally NOT work if you have set STDIO_MODE_ONLY to true.
python example_clients/streamable_http_client.py mcp call_tool --args '{
"name": "code_exec_python",
"arguments": {
"code": "import numpy as np; print(np.random.rand(50).tolist())",
"packages": ["numpy"]
}
}' | jq
Local STDIO
There are two ways to easily test out your MCP server in STDIO mode:
1. Local STDIO - Example Python STDIO Client
List tools:
python example_clients/stdio_client.py mcp list_tools | jq
Example tool call request:
python example_clients/stdio_client.py mcp call_tool --args '{
"name": "code_exec_python",
"arguments": {
"code": "import numpy as np; print(np.random.rand(50).tolist())",
"packages": ["numpy"]
}
}' | jq
2. Local STDIO - Direct Calls
Example tool call request:
cat <<EOF | python -m src.stdio_server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"code_exec_python","arguments":{"code":"import numpy as np; print(np.random.rand(50).tolist())","packages":["numpy"]}}}
EOF
(Note that the server expects the client to send a shutdown request, so you can stop the connection with CTRL-C)
Remote Testing
Remote Streamable HTTP, SSE
To test your remote Streamble HTTP or SSE server, you'll need to make sure a web process is actually spun up. To save on costs, by default this repository doesn't spin up web dynos on creation, as many folks only want to use STDIO mode (local and one-off dyno) requests:
heroku ps:scale web=1 -a $APP_NAME
You only need to do this once, unless you spin back down to 0 web dynos to save on costs (heroku ps:scale web=0 -a $APP_NAME). To confirm currently running dynos, use heroku ps -a $APP_NAME.
By default, this app deploys a Streamable HTTP MCP server - if you want to deploy an SSE server, run:
heroku config:set REMOTE_SERVER_TRANSPORT_MODULE=sse_server
Which will affect which server is run in the Procfile.
Next, run:
export API_KEY=$(heroku config:get API_KEY -a $APP_NAME)
export MCP_SERVER_URL=$(heroku info -s -a $APP_NAME | grep web_url | cut -d= -f2)
Next, you can run the same queries as shown in the Local SSE - Example Requests testing section - because you've set MCP_SERVER_URL, the client will call out to your deployed server.
Remote STDIO
There are two ways to test out your remote MCP server in STDIO mode:
1. Remote STDIO - Example Python STDIO Client, Running On-Server
To run against your deployed code, you can run the example client code on your deployed server inside a one-off dyno:
heroku run --app $APP_NAME -- bash -c 'python -m example_clients.stdio_client mcp list_tools | jq'
or:
heroku run --app $APP_NAME -- bash -c '
python -m example_clients.stdio_client mcp call_tool --args '\''{
"name": "code_exec_python",
"arguments": {
"code": "import numpy as np; print(np.random.rand(50).tolist())",
"packages": ["numpy"]
}
}'\'' | jq
'
2. Remote STDIO - Direct Calls to One-Off Dyno
Or, you can also run or simulate a client locally that sends your client-side requests to a one-off dyno:
heroku run --app "$APP_NAME" -- bash -c "python -m src.stdio_server 2> logs.txt" <<EOF
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"code_exec_python","arguments":{"code":"import numpy as np; print(np.random.rand(50).tolist())","packages":["numpy"]}}}
EOF
Again, note that since we're running our request through a single command, we're unable to simulate a client's shutdown request.
3. Coming Soon - Heroku MCP Gateway!
Soon, you'll also be able to connect up your MCP repo to Heroku's MCP Gateway, which will make streaming requests and responses from one-off MCP dynos simple!
The Heroku MCP Gateway implements a rendezvous protocol so that you can easily talk to your MCP server one-off dynos (code execution isolation!) with seamless back-and-forth communication.
After deploying and registering your MCP app on heroku, requests made to Heroku's v1/mcp/servers will show you your registered MCP tools, and requests made to v1/agents/heroku will be able to execute your MCP tools automatically via one-off dynos.
