How to Connect an MCP AI Agent to Your Project Workspace

If you want an AI assistant that actually understands your delivery work, the fastest path is to connect an MCP AI agent to your project workspace. KazTrack ships a built-in Model Context Protocol (MCP) server, so tools like Claude Code, Codex, or any MCP-compatible client can read pull request diffs, generate and run test cases, edit docs, and update sprints — all bounded by the permissions of the token you hand it. This tutorial walks through the full setup, from minting a token to verifying your first tool call.

Prerequisites

A KazTrack project where you are a member (any role can create a personal token).
An MCP client installed locally — Claude Code, Codex, or another MCP host.
Your workspace base URL (for example, https://app.kaztrack.com).
Familiarity with editing a JSON config file.

Step 1: Decide which token type you need

KazTrack issues two kinds of per-project tokens:

Personal token — acts as you. Any member can create one. The agent inherits exactly your permissions.
Service token — acts on behalf of automation and is created by members with the settings.mcp permission (managers and owners). Use these for CI jobs and shared bots.

The token fixes the active project, which is why MCP tools never ask for a project argument. Pick a personal token if you are experimenting on your own machine; pick a service token for unattended automation.

Step 2: Generate the token

Open your workspace and go to Settings → MCP.
Click Create token.
Name it something traceable, like claude-code-laptop or ci-nightly-tests.
Choose Personal or Service.
Copy the token immediately — it is shown only once.

Treat this token like a password. It grants the same access the owning user has in the UI, so store it in a secret manager rather than pasting it into shared chat.

Step 3: Add the MCP server to your client config

Point your client at the streamable HTTP endpoint, which lives at /mcp. Here is an illustrative client config block — note the bearer token placeholder and the endpoint:

{
  "mcpServers": {
    "kaztrack": {
      "type": "http",
      "url": "https://app.kaztrack.com/mcp",
      "headers": {
        "Authorization": "Bearer kzt_REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}

In Claude Code you can also register it from the command line:

claude mcp add --transport http kaztrack https://app.kaztrack.com/mcp \
  --header "Authorization: Bearer kzt_REPLACE_WITH_YOUR_TOKEN"

Replace the placeholder with the token from Step 2 and the host with your own workspace URL.

Step 4: Restart the client and confirm the connection

Restart your MCP client so it picks up the new server. Most clients expose a command to list connected servers and their tools. When the handshake succeeds, you should see the KazTrack tool catalog appear — tools grouped by domain such as pull requests, test cases, sprints, issues, reports, docs, and deploys.

If the agent reports zero tools, the connection failed. Jump to Troubleshooting before continuing.

Step 5: Verify with a safe, read-only call

Always start with a read before letting the agent write anything. Ask your agent to fetch the workspace identity:

“Use the KazTrack MCP server to show me this project’s name and my role.”

Under the hood the agent calls a project-info tool and returns the active project plus your effective permissions. This confirms two things at once: the token authenticates, and it is scoped to the project you expect.

Next, try a read against real work:

“List the open pull requests in this project, then pull the diff and assigned test cases for the most recent one.”

The agent reads the PR context — diff plus any test cases already attached — without changing anything.

Step 6: Let the agent take a bounded action

Once reads work, graduate to a write that respects RBAC. A good first action is advancing a workflow label:

“Move PR #142 to in_progress.”

The agent sets the workflow state, which maps to a GitHub label like in_progress and syncs back to the real pull request. Because the personal token inherits your permissions, the call only succeeds if you could do it in the UI. A viewer token will be refused — that is the safety model working as intended.

A practical pattern for QA agents looks like this:

Read the PR diff with the context tool.
Generate test cases from the diff (the agent can reason over it directly).
Assign those test cases to the PR.
Record pass/fail results.
Post a comment back to the GitHub PR summarizing the run.

Every step is gated by the token owner’s permissions, so an agent can never exceed what its human could do.

Troubleshooting

No tools listed / 401 Unauthorized — the bearer token is wrong, expired, or missing the Bearer prefix. Re-copy it from Settings → MCP and confirm the Authorization header is formatted exactly as shown.
403 on a write — the token’s user lacks the permission for that action. Personal tokens mirror UI permissions; ask an owner to adjust your role or use a service token created with the right access.
Connection refused or 404 — check the URL ends in /mcp and uses HTTPS. A trailing slash or the wrong host is the usual culprit.
Wrong project’s data — each token is bound to one project. If you see another project’s PRs, you generated the token from the wrong workspace; create a new one from the correct project.
Mutations silently do nothing — confirm the tool reported success rather than an error string; agents sometimes summarize a refusal as if it were a result.

Key takeaways

Connecting an MCP AI agent to your workspace takes three things: the right token type, the /mcp endpoint, and a habit of verifying reads before writes. Because tokens are per-project and permission-bounded, you can safely point automation at real pull requests, sprints, and docs without giving away the keys to the whole organization. Mint a personal token in KazTrack today and let your AI agent start reading diffs and running test cases within minutes.