Build your own Raia software developer

Want an agent that can actually change an app, run its checks and give you a preview to review? This guide connects a raia agent to a custom software-development MCP server, a GitHub repository and Vercel.

Start with one small demo app. Your first win is a working change on a separate branch, passing checks and a preview you can open. You can add a database after that works.

What you are setting up

MCP is the connection that lets an agent use tools. The instructions tell your agent how to work; the connected server supplies the actions it can take.

Your request → raia agent → authenticated MCP server
                              ↓
                      GitHub task branch
                              ↓
                 GitHub Actions checks + Vercel preview
                              ↓
                    You review the change
                              ↓
                  Merge → production deployment

A repository stores your app's files. A branch keeps a proposed change separate from the main version. A pull request, or PR, is the place to review that change before merging it. GitHub Actions runs automated checks. A preview lets you try the changed app before it becomes the main version.

The Software Builder example has one coding integration and two optional Supabase integrations. You only need the coding connection for this first walkthrough.

Before you begin

You need:

• Permission to create or configure a raia agent.
• Access to an approved copy of the coding MCP reference repository from your raia administrator; a private-repository 404 does not mean you entered the URL incorrectly.
• A GitHub account and one demo app repository you control. Keep the server's repository separate from the app the agent will edit.
• Git and Node.js 24 with npm on your computer. The commands below use PowerShell; on Windows, use npm.cmd if PowerShell blocks npm.
• A host for the MCP server. This guide uses Google Cloud Run. You need an approved Google Cloud project, billing and deployment permissions, plus the Google Cloud CLI.
• Vercel access if you want app previews. Docker is optional for the local container check.

If you only want an agent to use files, a browser or an isolated coding container on your own PC, use Connect local tools through a gateway instead. That is a different setup.

1. Prepare one demo app

Choose a small existing app that already starts successfully. For example, use a task tracker with sample tasks and no sign-in.

1. Create or choose its GitHub repository.
2. Make sure its default branch contains the app files, a package lock file and a README with the commands to run it.
3. Run the app's existing tests and build yourself once. Fix baseline failures before giving the agent a task.
4. Write down the exact repository name: OWNER/REPOSITORY.

Your first request can be as small as changing one heading. This makes it easier to tell whether the tools work before asking the agent to build a whole application.

2. Get the server code and check it

Obtain the approved repository URL or copy from your raia administrator. Clone it into a separate folder, then open PowerShell in that folder:

git clone YOUR_APPROVED_SERVER_REPOSITORY_URL raia-coding-mcp
cd raia-coding-mcp
node --version
npm ci
npm audit --omit=dev
npm test
npm run build

Replace the URL before running the command. Review the code before installing and running it. If you were given a ZIP, extract it and open the folder containing package.json instead of cloning.

If the audit reports high or critical issues, have the maintainer update the dependencies and review the affected paths, then rerun the audit, tests and build before continuing to hosting. Do not use npm audit fix --force blindly. Dependency advisories identify issues to review; they are not proof of a working exploit. Passing tests and a build do not make this reference secure or ready for public deployment.

Continue only after the dependency review and successful checks. A successful build checks the server code; it does not prove your GitHub credentials or Raia connection work yet.

3. Give the server access to just your demo repository

The server needs a GitHub credential to read and change the app. For a personal demo, create a fine-grained personal access token with an expiry date and access to only the selected demo repository.

In GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens, then create a token. Select the resource owner and your demo repository. Start with these repository permissions:

Use Actions read and write only if you enable the tool that starts an existing workflow. You do not need repository-creation or workflow-file editing permissions for the first task. Organization policy may require approval before a token works.

Save the token in your password manager or secret store. It becomes GITHUB_TOKEN on the server. Never put it in an agent prompt, a Git URL or a repository file.

For a shared customer service, use a properly implemented GitHub App installation flow with scoped, short-lived tokens. The demo's personal token setup is not that implementation. See GitHub's token guide.

4. Configure the server locally

Create a .env file in the server folder. Confirm .env is in .gitignore before adding secrets. Use your editor to enter:

PORT=3000
HOST=127.0.0.1
MCP_AUTH_TOKEN=YOUR_NEW_RANDOM_SECRET
GITHUB_TOKEN=YOUR_RESTRICTED_GITHUB_TOKEN
GITHUB_ONLY=true
ALLOWED_REPOSITORIES=OWNER/DEMO_REPOSITORY
ALLOWED_OWNERS=

Replace the placeholders. Generate a separate random MCP secret of at least 32 characters using your password manager. The MCP secret and GitHub token are different credentials. Raia uses the MCP secret to call your server; the server uses the GitHub token to call GitHub.

Leave ALLOWED_OWNERS empty for this walkthrough. In this reference implementation, an allowed owner grants access to repositories under that owner even when an exact repository list is also present. Filling both does not narrow access.

Keep GITHUB_ONLY=true. This exposes the GitHub workflow rather than enabling a general shell on the server.

The current reference build writes its local entry point to dist/src/index.js. Start it with Node's explicit environment-file option:

node --env-file=.env dist/src/index.js

Creating .env alone does not load it. Keep this terminal open. In another terminal, run:

Invoke-RestMethod http://127.0.0.1:3000/health

You should see ok: True and mode: github-only. This checks that the server is running in the intended mode. GitHub access is tested later.

Optional Docker check, after stopping the Node process with Ctrl+C:

docker build -t raia-coding-mcp .
docker run --rm --env-file .env -e HOST=0.0.0.0 -p 127.0.0.1:3000:3000 raia-coding-mcp

Run the same health check again. Docker's image uses a different compiled-file layout internally; let its Dockerfile start the server.

5. Host the MCP server

Before hosting: Use an updated, maintainer-reviewed server copy. Resolve high or critical audit findings with the maintainer and rerun the audit, tests and build before following the hosting instructions below.

Raia runs in the cloud. It cannot reach localhost on your computer. Give the server its own HTTPS address.

Cloud Run is one hosting option for this Node/Express reference. It requires billing and may incur build, storage and runtime charges. Cloudflare Workers is not a drop-in replacement for this Docker/Express server.

Prepare the Google Cloud project

Install the current Google Cloud CLI. In your terminal, run:

gcloud auth login

Sign in to the approved Google account, then prepare its project:

1. Select an approved project and region.
2. Enable Cloud Run, Cloud Build, Artifact Registry and Secret Manager APIs.
3. Give your deployer and build identities the roles required by Google's source deployment guide. Create a dedicated runtime service account for this server.
4. In Secret Manager, create raia-mcp-auth and raia-github-token. Store the corresponding values from your local setup as secret versions.
5. Grant the runtime service account Secret Manager Secret Accessor on those two secrets. See using secrets in Cloud Run.
6. Check that .gcloudignore excludes .env, other secret files, node_modules and local build output. Run gcloud meta list-files-for-upload from the server folder and check that no credential files would be uploaded.

Do not copy your local .env into the deployed image. Cloud Run should inject the secret values.

Deploy from the server folder

The following is a template command. Replace every uppercase placeholder, including the service account and repository. The secret suffix :1 means version 1; use the version you created.

gcloud run deploy raia-coding-mcp --source . --project YOUR_PROJECT_ID --region YOUR_REGION --port 3000 --service-account YOUR_RUNTIME_SERVICE_ACCOUNT_EMAIL --set-env-vars "GITHUB_ONLY=true,ALLOWED_REPOSITORIES=OWNER/DEMO_REPOSITORY" --set-secrets "MCP_AUTH_TOKEN=raia-mcp-auth:1,GITHUB_TOKEN=raia-github-token:1" --max-instances 1 --no-invoker-iam-check

The final flag makes the HTTP service reachable without a Google identity token. Your server still checks its MCP secret on /mcp. This is necessary for this direct shared-secret connection; do not remove the server's authentication check. If your organization disallows public invocation, use an administrator-approved access design instead. See Cloud Run public access.

This reference keeps MCP sessions in memory. One instance reduces cross-instance session problems, but restarts still lose sessions. Reconnect if a session expires. It is a demo starting point, not a highly available service.

The reference also contains dashboard routes; they are not needed for this tutorial, and dashboard task creation is unauthenticated in the reviewed version. Before using the server beyond an isolated demo, have its maintainer restrict or remove unused routes, add rate limits and review authentication, session handling and logging. A secret on /mcp does not protect every route automatically.

Check the hosted address

1. Copy the service URL printed by Cloud Run.
2. Open https://YOUR_SERVICE_HOST/health. Confirm the mode is github-only.
3. Open https://YOUR_SERVICE_HOST/mcp without credentials. An unauthorized response is expected.
4. Keep the full MCP address, ending in /mcp, for the Raia connection.

A healthy endpoint does not prove that tool discovery or GitHub writes work. The next steps check those separately.

6. Create your software-building agent

Create an agent in your own raia organization, or use a demo agent you are allowed to configure. Name it something clear, such as Software Builder.

Open the agent, choose Train → Agent Instructions, and enter or adapt the prompt below under Current Instructions. Replace the repository placeholder, then save your instructions.

You help me improve the demo app in OWNER/DEMO_REPOSITORY.

Before making changes:
- Read the repository structure and relevant files.
- State the requested result and how you will verify it.
- Ask if missing information would change the scope or create risk.

When working:
- Use only tools that are actually connected and enabled.
- Keep changes small and follow the repository's conventions.
- Write only to a new raia/* task branch. Never push directly to main.
- Open a draft pull request and identify its head commit.
- Use the repository's existing GitHub Actions checks. Inspect their
  actual results and logs; never invent a test result.
- Return the PR link, available preview link, checks and remaining issues.

Stop and ask before changing authentication, permissions, payments,
secrets, infrastructure, workflow definitions or database schemas.
Do not merge, deploy to production or create paid resources without
specific approval. If a tool is unavailable or a check fails, say so.

This is a GitHub-based workflow. Do not tell the agent it has a terminal, browser or local coding workspace unless you have connected those tools separately. A good instruction cannot create a missing capability.

7. Connect the coding server in raia

Open the agent's MCP Integrations skill, choose the Integrations tab and select Add Integration. Use MCP Integrations if you need help adding the skill first.

Enter a name and description that explain what this connection is for.

Paste only the raw MCP secret into Authorization. Do not add Bearer; raia adds that prefix to the request header. Direct HTTP clients still send Authorization: Bearer <secret>. Do not paste the GitHub token here.

Select Get Available Tools. If discovery fails, fix the URL, transport or authentication before continuing.

Start with read-only tools

Select github_repository_tree and github_read_file, then save. The example screenshot shows a more fully configured agent; you do not need to enable all of its tools.

In Copilot, start a conversation with your agent and ask:

Compare the reply with GitHub. Open the function results in the conversation to confirm the agent actually read the repository. If it guessed the contents, the connection is not ready.

8. Add checks and a preview

Before enabling writes, give the demo app a reliable way to verify changes.

GitHub Actions

Use the app's existing workflow if it already has one. It should run relevant tests and a build for pull requests. If you are creating a Node app workflow, this small example assumes the repository already has a lock file and working test and build scripts:

name: Verify app
on:
  pull_request:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build

Save it as .github/workflows/verify.yml through your normal reviewed setup process. Use your app's supported Node version and actual commands. Do not add a fake passing test just to get a green badge. A manually dispatched workflow needs workflow_dispatch and a workflow present on the default branch.

Protect the main branch with required PR reviews and required checks where your GitHub plan supports them. Server tool restrictions and agent instructions do not replace repository controls.

Vercel

1. In Vercel, add a new project and import the demo app repository, not the MCP server repository.
2. Allow the GitHub integration access to that repository.
3. Check the detected framework, root directory, build command and output directory against your app.
4. Add only the environment variables the app needs, with the correct Preview or Production scope.
5. Deploy the baseline app and open it.

After the Git integration is configured, eligible branch pushes and pull requests can generate preview deployments. Check the deployment's actual status and access settings. A preview may require sign-in; it is not automatically public. See Vercel's GitHub integration.

You do not need a VERCEL_TOKEN in the MCP server for Git-connected previews alone. Add a dedicated token and the appropriate team setting only if you deliberately want the server's Vercel API tools.

9. Let the agent make one small change

Return to the MCP integration. Keep the read tools and add:

• github_create_branch
• github_write_file and/or github_commit_files
• github_open_pull_request
• github_workflow_runs, github_workflow_run_jobs, github_workflow_job_logs
• github_check_runs and github_pull_request

Enable github_dispatch_workflow only if you configured that workflow and its token permission. Leave repository creation, merge, database and infrastructure tools off for your first exercise. Save the updated selection.

Try this prompt:

A useful result gives you a reviewable change, not just “done.” Open the PR and preview yourself:

If the agent cannot open the preview in a browser, it should ask you to check the page rather than claiming it looks correct.

Optional: if your server offers frontend_design_taste_rules, enable it for UI-design work. It retrieves design guidance; it does not grant browser or terminal access. Ask for new, redesign or from_screenshot guidance to match your task, then completion_review. Your brief, brand requirements and security constraints still apply.

For this first exercise, merge manually after review if you want the change published. With the production branch connected to Vercel, merging can trigger a production deployment. A later automated merge setup must tie approval to the exact current PR commit and independently enforce human approval. A tool argument named userApproved is not proof that a person approved anything.

10. Add a database only when the app needs one

You can build and review a simple page without a database. Add Supabase when you need shared saved data, user accounts or server-side operations.

Keep account-level project management separate from access to an individual database. The Software Builder example has both kinds of connection, but you do not need to copy that full setup.

For a development project, follow Supabase's MCP setup, scope the connection to that project, and begin with read-only access. Add migration or SQL tools only when you understand and approve the changes they can make.

Browser apps may use a publishable/anon key with appropriate row-level security. Keep service-role keys, database passwords and other privileged secrets on the server. Before claiming a user-data app is ready, test that one user cannot read or change another user's data.

A connection named “FreeProjectManager” does not guarantee free service. Review current costs before creating resources.

If something does not work

Stop or extend the demo

When finished, disable the integration if you no longer want the agent to use it. To stop server access entirely, stop the hosted service or revoke its credential; disabling the raia connection alone does not shut down the server. Revoke demo tokens and remove unused cloud resources through their normal controls when no longer needed.

For a next project, give the agent a clear result, a small scope and specific checks. Add tools only when the next task needs them. For separate local capabilities, continue with browser control or an isolated coding workspace.